> ## Documentation Index > Fetch the complete documentation index at: https://docs.memvid.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting - CLI > Common errors, solutions, and diagnostic commands This guide covers common CLI errors and how to resolve them. ## Exit Codes The CLI uses specific exit codes to indicate error types: | Exit Code | Meaning | Description | | --------- | ---------- | --------------------------------------------- | | 0 | Success | Command completed successfully | | 1 | Generic | General error | | 2 | Capacity | Storage capacity exceeded or API key required | | 3 | Lock | File lock conflict | | 4 | Corruption | File 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:** ```bash theme={null} # 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 ``` 2. **Create a new file with larger capacity:** ```bash theme={null} # Create with specific size memvid create newfile.mv2 --size 2GB ``` 3. **Check current usage:** ```bash theme={null} 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:** ```bash theme={null} memvid who myfile.mv2 ``` 2. **Request the writer to release:** ```bash theme={null} memvid nudge myfile.mv2 ``` 3. **Find the process holding the lock:** ```bash theme={null} # macOS/Linux lsof myfile.mv2 ``` 4. **Wait and retry with timeout:** ```bash theme={null} memvid put myfile.mv2 --input doc.pdf --lock-timeout 5000 ``` 5. **Force takeover of stale lock:** ```bash theme={null} 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:** ```bash theme={null} # Quick verification memvid verify myfile.mv2 # Deep verification memvid verify myfile.mv2 --deep ``` 2. **Run the doctor:** ```bash theme={null} # 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 ``` 3. **Verify single-file integrity:** ```bash theme={null} memvid verify-single-file myfile.mv2 ``` ### Time Index Issues **Symptom:** ``` TimeIndexSortOrder: Failed in memvid verify --deep Error: TimeIndexMissing ``` **Solution:** ```bash theme={null} memvid doctor myfile.mv2 --rebuild-time-index memvid verify myfile.mv2 --deep ``` ### Search Returns Empty Results **Symptom:** ```bash theme={null} $ 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:** ```bash theme={null} memvid stats myfile.mv2 --json | grep has_lex_index ``` 2. **Rebuild the lexical index:** ```bash theme={null} memvid doctor myfile.mv2 --rebuild-lex-index ``` 3. **Try different search modes:** ```bash theme={null} # 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 ``` 4. **Check if content exists:** ```bash theme={null} memvid timeline myfile.mv2 --limit 5 memvid view myfile.mv2 --frame-id 1 ``` ### Invalid Flag Error **Symptom:** ``` error: unexpected argument '--nonexistent-flag' ``` **Solution:** ```bash theme={null} memvid --help ``` ### File Already Exists **Symptom:** ``` Error: File 'myfile.mv2' already exists ``` **Solution:** ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # Who holds the lock? memvid who myfile.mv2 # Request release memvid nudge myfile.mv2 ``` ### Doctor Commands ```bash theme={null} # 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 ```bash theme={null} # 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:** ```bash theme={null} # 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:** ```bash theme={null} memvid put myfile.mv2 --input large-dataset/ \ --parallel-segments \ --parallel-threads 4 \ --parallel-queue-depth 8 ``` ### Optimizing Ingestion Speed 1. **Use batch operations:** ```bash theme={null} # Ingest entire directory at once memvid put myfile.mv2 --input ./docs/ ``` 2. **Enable parallel segments:** ```bash theme={null} memvid put myfile.mv2 --input ./docs/ --parallel-segments ``` 3. **Skip embeddings for faster ingestion:** ```bash theme={null} memvid put myfile.mv2 --input ./docs/ --no-embedding ``` 4. **Use vector compression for smaller files:** ```bash theme={null} memvid put myfile.mv2 --input ./docs/ --vector-compression ``` ## Cleaning Up Stale Files If you see leftover files from older versions: ```bash theme={null} # 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 ```bash theme={null} # 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: ```bash theme={null} # 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 ```