Troubleshooting Guide¶

This guide covers common issues, error messages, and their solutions when working with Uni.

Quick Diagnostics¶

# Check database info
uni query "SHOW DATABASE" --path ./storage

# Check schema
uni query "CALL uni.schema.labels() YIELD label RETURN label" --path ./storage

# Basic stats
uni query "SHOW STATISTICS" --path ./storage

# View recent logs
RUST_LOG=uni_db=debug uni query "RETURN 1" --path ./storage 2>&1 | tail -50

Common Issues¶

Installation Problems¶

Rust Version Incompatible¶

Symptom:

error: package `uni-db v0.1.0` cannot be built because it requires rustc 1.91 or newer

Solution:

# Update Rust
rustup update stable

# Verify version
rustc --version  # Should be 1.91+

Missing System Dependencies¶

Symptom:

error: failed to run custom build command for `openssl-sys`

Solution:

# Ubuntu/Debian
sudo apt install pkg-config libssl-dev

# macOS
brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)

# Fedora
sudo dnf install openssl-devel

Build Fails with SIMD Errors¶

Symptom:

error: unknown feature 'avx2'

Solution:

# Build without SIMD optimizations
cargo build --release --no-default-features

# Or specify target CPU
RUSTFLAGS="-C target-cpu=native" cargo build --release

Storage Issues¶

Cannot Open Storage¶

Symptom:

Error: Failed to open storage at ./storage: No such file or directory

Solution:

# Check path exists
ls -la ./storage

# Create storage (embedded mode)
uni query "RETURN 1" --path ./storage

// Or create programmatically
let db = Uni::open("./storage").build().await?;

Corrupted Storage¶

Symptom:

Error: Invalid manifest at version 42: CRC mismatch

Solution:

# Restore from snapshot (recommended)
uni snapshot list --path ./storage
uni snapshot restore <snapshot_id> --path ./storage

# Or via Cypher
uni query "CALL uni.admin.snapshot.list()" --path ./storage
uni query "CALL uni.admin.snapshot.restore('<snapshot_id>')" --path ./storage

# If no snapshot exists, re-import or rebuild the database

Out of Disk Space¶

Symptom:

Error: Failed to write to storage: No space left on device

Solution:

# Check disk usage
df -h ./storage

# Compact storage
uni query "CALL uni.admin.compact()" --path ./storage

# Move storage to a larger disk (stop any running processes first)
mv ./storage /larger-disk/storage

Query Issues¶

Parse Errors¶

Symptom:

Error: Parse error at line 1, column 15: unexpected token

Common Causes:

1. Missing quotes around strings:

// Wrong
WHERE p.title = My Paper

// Correct
WHERE p.title = 'My Paper'

1. Wrong comparison operator:

// Wrong (SQL style)
WHERE p.year == 2023

// Correct (Cypher style)
WHERE p.year = 2023

1. Missing relationship direction:

   // Wrong
   MATCH (a)-[r]-(b)  // Ambiguous in some contexts
   
   // Better (explicit direction)
   MATCH (a)-[r]->(b)
   

Semantic Errors¶

Symptom:

Error: Unknown label 'Paper'

Solution:

# List available labels
uni query "CALL uni.schema.labels() YIELD label RETURN label" --path ./storage

# Check spelling/case
# Labels are case-sensitive: Paper != paper

Symptom:

Error: Unknown property 'year' for label 'Paper'

Solution:

# List properties for label
uni query "CALL uni.schema.labelInfo('Paper')" --path ./storage

# Add property to schema if needed
uni query "ALTER LABEL Paper ADD PROPERTY year INT32" --path ./storage

Query Timeout¶

Symptom:

Error: Query timeout after 300 seconds

Solutions:

1. Add LIMIT:

   MATCH (p:Paper)-[:CITES]->(cited)
   RETURN p.title, cited.title
   LIMIT 1000  // Add limit
   

2. Add filters:

   MATCH (p:Paper)-[:CITES]->(cited)
   WHERE p.year > 2020  // Filter early
   RETURN p.title, cited.title
   

3. Increase timeout:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.query_timeout = Duration::from_secs(600);  // 10 minutes
   

4. Check query plan:

   uni query "EXPLAIN MATCH (p:Paper)..." --path ./storage
   # Look for missing indexes
   

Out of Memory¶

Symptom:

Error: Query execution failed: Out of memory

Solutions:

1. Reduce result size:

   MATCH (p:Paper)
   RETURN p.title  // Only needed columns
   LIMIT 10000     // Reasonable limit
   

2. Stream results:

   let mut cursor = session.query_with(query).cursor().await?;
   while let Some(row) = cursor.next().await? {
       // Process a row at a time
   }
   

3. Increase memory limit:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.max_query_memory = 8 * 1024 * 1024 * 1024;  // 8 GB
   

4. Reduce batch size:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.batch_size = 1024;  // Smaller batches
   

Index Issues¶

Vector Search Returns Poor Results¶

Symptom: Results are not semantically similar to the query.

Causes and Solutions:

1. Embedding model mismatch: Ensure the same embedding model is used for indexing and querying.

2. Auto-embedding routes through any provider in the catalog. local/candle (BERT-style) and local/onnx (FastEmbed-compatible alias strings via the unified ONNX Embed task) are the two local backends. Remote APIs (OpenAI, Gemini, Vertex, Voyage, Cohere) are supported through their respective provider-* features.

3. Dimension mismatch: since 2.5.0 this surfaces as an error, not as poor results — a query vector whose length differs from the declared column dimension fails with "vector dimension mismatch" (previously it silently returned 0 rows), and wrong-length writes fail with a TypeError.

   # Check schema dimensions
   uni query "CALL uni.schema.labelInfo('Paper')" --path ./storage
   

   // Ensure query vector matches
   assert_eq!(query_vec.len(), 768);
   

4. Index mismatch or missing index:

   # Check indexes
   uni query "SHOW INDEXES" --path ./storage
   # or
   uni query "CALL uni.schema.indexes()" --path ./storage
   

   If you need a different distance metric, recreate the index via Rust/Python APIs (Cypher DDL uses cosine today).

Index Not Being Used¶

Symptom: Query is slow despite having an index.

Diagnosis:

uni query "EXPLAIN MATCH (p:Paper) WHERE p.year > 2020 RETURN p" --path ./storage

Common Causes:

1. Function on indexed column:

// Index NOT used (function applied to column)
WHERE LOWER(p.venue) = 'neurips'

// Index used
WHERE p.venue = 'NeurIPS'

1. OR conditions:

// May not use index efficiently
WHERE p.year > 2020 OR p.venue = 'NeurIPS'

// Better: split into UNION (if supported)

1. Leading wildcard:

// Cannot use index
WHERE p.title CONTAINS 'attention'

// Can use full-text index (if available)

1. Low selectivity:

// If 80% of data matches, full scan may be faster
WHERE p.year > 2000

Index Build Fails¶

Symptom:

Error: Failed to build vector index: out of memory

Solutions:

1. Use IVF_PQ or Flat instead of HNSW:

   CREATE VECTOR INDEX paper_embeddings
   FOR (p:Paper) ON p.embedding
   OPTIONS { type: 'ivf_pq' }  // Less memory
   

2. Build asynchronously after bulk load:

   let _task_id = db.indexes().rebuild("Paper", true).await?;
   

   Or use bulk_writer().async_indexes(true).

Import Issues (CLI)¶

The CLI importer expects the Semantic Scholar demo format (vid, src_vid, dst_vid).

Missing Required Fields¶

Symptom:

Error: Missing vid/src_vid/dst_vid

Solution: Ensure your JSONL includes: - Papers: vid, title, year, citation_count, embedding - Citations: src_vid, dst_vid

Invalid VID References¶

Symptom:

Error: Missing src_vid or dst_vid

Solution: Ensure citations reference existing paper VIDs.

Embedding Dimension Mismatch¶

Symptom:

Error: Vector dimension mismatch: expected 768, got 384

Solution:

# Check schema
uni query "CALL uni.schema.labelInfo('Paper')" --path ./storage

Performance Issues¶

Slow Traversals¶

Symptom: Graph traversals take >100ms.

Diagnosis:

uni query "PROFILE MATCH (p:Paper)-[:CITES]->(c) RETURN COUNT(c)" --path ./storage

Solutions:

1. Warm the adjacency cache:

   // Run a small traversal once to warm cache
   MATCH (p:Paper)-[:CITES]->(c) RETURN COUNT(c)
   

2. Increase cache size:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.cache_size = 2_000_000_000; // bytes
   

3. Add LIMIT to multi-hop:

   MATCH (p:Paper)-[:CITES*1..3]->(end)
   RETURN DISTINCT end
   LIMIT 1000
   

4. Stop asking for whole paths. A variable-length pattern only expands individual paths when the query binds one. Returning endpoints skips that work entirely, and on a graph with cycles the difference is not marginal — the number of distinct paths grows combinatorially with the hop bound while the underlying search does not.

// Expensive: every distinct path is built
MATCH p = (a:Paper)-[:CITES*1..6]->(b) RETURN p

// Cheap: same search, no path expansion
MATCH (a:Paper)-[:CITES*1..6]->(b) RETURN DISTINCT b

If you want one path rather than all of them, use shortestPath, which stops at the first one it finds.

A Path Query Times Out or Exhausts Memory¶

Symptom: MATCH p = (a)-[:R*]->(b) RETURN p (or count(p)) fails with a timeout or a ResourcesExhausted error, while the same pattern returning endpoints succeeds.

Cause: This is path expansion, not the graph search. Over a cyclic graph the set of distinct paths is combinatorial, so the query is asking for an unbounded amount of work. The error names whichever declared limit stopped it.

Solutions, in order of effectiveness:

1. Return endpoints instead of p — see above. Usually this is the whole fix.
2. Add a LIMIT. It stops the expansion rather than trimming its output, so a small limit costs a small amount of work. Note the floor: the graph search still runs in full, and the limit applies a batch (8192 rows) at a time, so any limit up to 8192 costs the same.
3. Write an upper hop bound — [*1..6] rather than [*]. Remember an omitted bound means 100, not infinity.
4. Raise the ceiling only once the above are exhausted: query_with(...).max_memory(...) / .timeout(...).

If rows come back with a warning about a safety cap instead, that is a different condition: the search was abandoned and the results are incomplete. Narrow the pattern with a hop bound, a relationship type, or a label on the target.

High Memory Usage¶

Symptom: Process using more memory than expected.

Diagnosis: Use OS-level tools (top, htop) and PROFILE output.

Solutions:

1. Reduce cache sizes:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.cache_size = 500_000_000; // bytes
   

2. Flush L0 more frequently:

   use uni_db::UniConfig;
   
   let mut config = UniConfig::default();
   config.auto_flush_threshold = 5_000;
   config.auto_flush_interval = Some(Duration::from_secs(2));
   

3. Use streaming queries:

   let mut cursor = session.query_with(query).cursor().await?;
   while let Some(_row) = cursor.next().await? {
       // Process results without loading all into memory
   }
   

Error Reference¶

Storage / IO Errors¶

Query / Schema Errors¶

Debugging Tips¶

Enable Verbose Logging¶

# All Uni logs at debug level
RUST_LOG=uni_db=debug uni query "..." --path ./storage

# Specific module
RUST_LOG=uni_db::storage=trace,uni_db::query=debug uni query "..."

# Include Lance logs
RUST_LOG=uni_db=debug,lance=info uni query "..."

Query Profiling¶

# Get execution profile
uni query "PROFILE MATCH (p:Paper) WHERE p.year > 2020 RETURN COUNT(p)" --path ./storage

# Output shows:
# - Time per operator
# - Rows processed
# - Index usage
# - Memory usage

Storage Inspection¶

# List all datasets
ls -la ./storage/vertices/
ls -la ./storage/edges/
ls -la ./storage/adjacency/

# Check Lance dataset info
# View on-disk schema
cat ./storage/catalog/schema.json | jq .

Memory Profiling¶

# Run with verbose logging
RUST_LOG=uni_db=debug uni query "..."

# Use heaptrack (Linux)
heaptrack uni query "..."
heaptrack_gui heaptrack.uni.*.gz

Getting Help¶

Resources¶

• Documentation: https://rustic-ai.github.io/uni-db/
• GitHub Issues: https://github.com/rustic-ai/uni-db/issues
• Discussions: https://github.com/rustic-ai/uni-db/discussions

Reporting Bugs¶

When reporting issues, include:

1. Uni version: uni --version
2. Rust version: rustc --version
3. OS and version
4. Minimal reproduction steps
5. Error messages (full output)
6. Query plan (if query-related): EXPLAIN ...
7. Storage stats: uni stats --path ./storage

Next Steps¶

• Configuration Reference — All configuration options
• Performance Tuning — Optimization strategies
• Glossary — Terminology reference