Skip to main content
This guide covers common CLI errors and how to resolve them.

​
Exit Codes

The CLI uses specific exit codes to indicate error types:
Exit CodeMeaningDescription
0SuccessCommand completed successfully
1GenericGeneral error
2CapacityStorage capacity exceeded or API key required
3LockFile lock conflict
4CorruptionFile corruption detected

​
Common Errors

​
Capacity Exceeded

Symptom: 
Error: CapacityExceeded
Current usage: 950 MB
Capacity limit: 1 GB
Required space: 100 MB
Causes:
  • File has reached its storage limit
  • Adding content that would exceed capacity
Solutions:
  1. Delete unused frames:
# List frames to find candidates for deletion
memvid timeline myfile.mv2 --limit 100

# Delete a specific frame
memvid delete myfile.mv2 --frame-id 42 --yes

# Compact the file to reclaim space
memvid doctor myfile.mv2 --vacuum
  1. Create a new file with larger capacity:
# Create with specific size
memvid create newfile.mv2 --size 2GB
  1. Check current usage:
memvid stats myfile.mv2

​
Lock Errors

Symptom: 
Error: File is locked by another process
Causes:
  • Another process is writing to the file
  • A previous process crashed without releasing the lock
  • Lock is held by a stale process
Solutions:
  1. Check who holds the lock:
memvid who myfile.mv2
  1. Request the writer to release:
memvid nudge myfile.mv2
  1. Find the process holding the lock:
# macOS/Linux
lsof myfile.mv2
  1. Wait and retry with timeout:
memvid put myfile.mv2 --input doc.pdf --lock-timeout 5000
  1. Force takeover of stale lock:
memvid put myfile.mv2 --input doc.pdf --force
Only use --force if you’re certain the previous writer has crashed. Forcing a lock on an active writer can cause corruption.

​
Corrupted File

Symptom: 
Error: CorruptToc - Table of Contents checksum mismatch
Error: InvalidHeader - Header magic bytes invalid
Causes:
  • File was corrupted during transfer
  • Crash during write operation
  • Disk errors
Solutions:
  1. Verify the file:
# Quick verification
memvid verify myfile.mv2

# Deep verification
memvid verify myfile.mv2 --deep
  1. Run the doctor:
# Preview repairs
memvid doctor myfile.mv2 --plan-only

# Rebuild specific index
memvid doctor myfile.mv2 --rebuild-time-index
memvid doctor myfile.mv2 --rebuild-lex-index
memvid doctor myfile.mv2 --rebuild-vec-index
  1. Verify single-file integrity:
memvid verify-single-file myfile.mv2

​
Time Index Issues

Symptom: 
TimeIndexSortOrder: Failed in memvid verify --deep
Error: TimeIndexMissing
Solution: 
memvid doctor myfile.mv2 --rebuild-time-index
memvid verify myfile.mv2 --deep

​
Search Returns Empty Results

Symptom: 
$ memvid find myfile.mv2 --query "test"
[]
Causes:
  • Lexical index not built
  • Content not indexed
  • Query doesn’t match any content
Solutions:
  1. Check index status:
memvid stats myfile.mv2 --json | grep has_lex_index
  1. Rebuild the lexical index:
memvid doctor myfile.mv2 --rebuild-lex-index
  1. Try different search modes:
# Lexical only
memvid find myfile.mv2 --query "test" --mode lex

# Semantic only
memvid find myfile.mv2 --query "test" --mode sem

# Hybrid (default)
memvid find myfile.mv2 --query "test" --mode auto
  1. Check if content exists:
memvid timeline myfile.mv2 --limit 5
memvid view myfile.mv2 --frame-id 1

​
Invalid Flag Error

Symptom: 
error: unexpected argument '--nonexistent-flag'
Solution: 
memvid <command> --help

​
File Already Exists

Symptom: 
Error: File 'myfile.mv2' already exists
Solution: 
# Remove existing file first
rm myfile.mv2
memvid create myfile.mv2

# Or use a different name
memvid create myfile-v2.mv2

​
Diagnostic Commands

​
Check File Health

# Basic stats
memvid stats myfile.mv2

# JSON output for scripting
memvid stats myfile.mv2 --json

# Verify integrity
memvid verify myfile.mv2

# Deep verification
memvid verify myfile.mv2 --deep

# Check for sidecar files
memvid verify-single-file myfile.mv2

​
Inspect Lock State

# Who holds the lock?
memvid who myfile.mv2

# Request release
memvid nudge myfile.mv2

​
Doctor Commands

# Preview what would be fixed
memvid doctor myfile.mv2 --plan-only

# Rebuild time index
memvid doctor myfile.mv2 --rebuild-time-index

# Rebuild lexical index
memvid doctor myfile.mv2 --rebuild-lex-index

# Rebuild vector index
memvid doctor myfile.mv2 --rebuild-vec-index

# Compact deleted frames
memvid doctor myfile.mv2 --vacuum

# Fix multiple issues
memvid doctor myfile.mv2 --rebuild-time-index --rebuild-lex-index

​
View Frame Details

# View by frame ID
memvid view myfile.mv2 --frame-id 1

# View by URI
memvid view myfile.mv2 --uri "mv2://docs/readme.md"

# JSON output
memvid view myfile.mv2 --frame-id 1 --json

# Preview media
memvid view myfile.mv2 --frame-id 1 --preview

​
Memory and Performance

​
Increasing Memory for Large Files

For large ingestion operations, you may need to increase available memory: Environment variables: 
# Set model cache directory
export MEMVID_MODELS_DIR=~/.memvid/models

# Enable offline mode (skip model downloads)
export MEMVID_OFFLINE=1

# Control parallel ingestion
export MEMVID_PARALLEL_SEGMENTS=1
CLI flags for parallel ingestion: 
memvid put myfile.mv2 --input large-dataset/ \
  --parallel-segments \
  --parallel-threads 4 \
  --parallel-queue-depth 8

​
Optimizing Ingestion Speed

  1. Use batch operations:
# Ingest entire directory at once
memvid put myfile.mv2 --input ./docs/
  1. Enable parallel segments:
memvid put myfile.mv2 --input ./docs/ --parallel-segments
  1. Skip embeddings for faster ingestion:
memvid put myfile.mv2 --input ./docs/ --no-embedding
  1. Use vector compression for smaller files:
memvid put myfile.mv2 --input ./docs/ --vector-compression

​
Cleaning Up Stale Files

If you see leftover files from older versions: 
# Check for sidecars
ls -la myfile.mv2*

# Remove any leftover files
rm -f myfile.mv2-wal myfile.mv2-shm myfile.mv2.lock

# Verify clean state
memvid verify-single-file myfile.mv2

​
Getting Help

# General help
memvid --help

# Command-specific help
memvid create --help
memvid put --help
memvid find --help
memvid doctor --help

# Version info
memvid version

​
Verbose Output

Enable debug logging for troubleshooting: 
# Increase verbosity
memvid -v find myfile.mv2 --query "test"    # WARN
memvid -vv find myfile.mv2 --query "test"   # INFO
memvid -vvv find myfile.mv2 --query "test"  # DEBUG
memvid -vvvv find myfile.mv2 --query "test" # TRACE