This guide covers common CLI errors and how to resolve them.
Exit Codes
The CLI uses specific exit codes to indicate error types:
Common Errors
Capacity Exceeded
Symptom:
Causes:
- File has reached its storage limit
- Adding content that would exceed capacity
Solutions:
- Delete unused frames:
- Create a new file with larger capacity:
- Check current usage:
Lock Errors
Symptom:
Causes:
- Another process is writing to the file
- A previous process crashed without releasing the lock
- Lock is held by a stale process
Solutions:
- Check who holds the lock:
- Request the writer to release:
- Find the process holding the lock:
- Wait and retry with timeout:
- Force takeover of stale lock:
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:
Causes:
- File was corrupted during transfer
- Crash during write operation
- Disk errors
Solutions:
- Verify the file:
- Run the doctor:
- Verify single-file integrity:
Time Index Issues
Symptom:
Solution:
Search Returns Empty Results
Symptom:
Causes:
- Lexical index not built
- Content not indexed
- Query doesn’t match any content
Solutions:
- Check index status:
- Rebuild the lexical index:
- Try different search modes:
- Check if content exists:
Invalid Flag Error
Symptom:
Solution:
File Already Exists
Symptom:
Solution:
Diagnostic Commands
Check File Health
Inspect Lock State
Doctor Commands
View Frame Details
Increasing Memory for Large Files
For large ingestion operations, you may need to increase available memory:
Environment variables:
CLI flags for parallel ingestion:
Optimizing Ingestion Speed
- Use batch operations:
- Enable parallel segments:
- Skip embeddings for faster ingestion:
- Use vector compression for smaller files:
Cleaning Up Stale Files
If you see leftover files from older versions:
Getting Help
Verbose Output
Enable debug logging for troubleshooting:
