Troubleshooting Guide

This guide walks through diagnosing and resolving the most common issues you’ll encounter with Memvid.

Quick Diagnosis

Run these commands to quickly identify issues:

# Check file health
memvid verify knowledge.mv2 --deep

# View file stats
memvid stats knowledge.mv2 --json

# Check for locks
lsof knowledge.mv2

Common Issues

”File is locked” when opening

Symptoms

FileLocked: File is locked by another process
Operations hang indefinitely
Cannot open file in Python/Node.js

Diagnosis

# Find process holding the lock
lsof knowledge.mv2

# Check for zombie processes
ps aux | grep memvid

Solution

Wait for the other process to finish
Kill the blocking process (if stuck):
kill -9 <PID>

Open in read-only mode:

mem = use('basic', 'knowledge.mv2', read_only=True)

Check for crashed processes - if a process crashed while holding a lock, restart your terminal/IDE

Search returns no results

Symptoms

mem.find() returns empty results
CLI search shows “0 results”
Expected documents not appearing

Diagnosis

# Check if file has content
memvid stats knowledge.mv2

# Check which indices are enabled
memvid info knowledge.mv2

# Try different search modes
memvid find knowledge.mv2 --query "test" --mode lex
memvid find knowledge.mv2 --query "test" --mode sem

Solution

Verify content exists:

memvid timeline knowledge.mv2 --limit 10

Check search mode - try lex for exact matches, sem for semantic:

# Exact keyword match
results = mem.find('exact phrase', mode='lex')

# Semantic/conceptual match
results = mem.find('related concept', mode='sem')

Rebuild indices if they’re corrupted:

memvid doctor knowledge.mv2 --rebuild-lex-index --rebuild-vec-index

Check embeddings were enabled during ingestion:

memvid put knowledge.mv2 --input doc.pdf --embeddings

“CapacityExceeded” error

Symptoms

CapacityExceeded: Memory file exceeded capacity limit
put() operations fail
Cannot add new content

Diagnosis

# Check current usage
memvid stats knowledge.mv2 --json | jq '.size_bytes, .capacity_bytes'

# Check ticket info
memvid tickets list knowledge.mv2

Solution

Upgrade your plan for more capacity:

memvid tickets sync knowledge.mv2 --memory-id YOUR_ID

Delete old content:

memvid delete knowledge.mv2 --before "2024-01-01" --yes

Vacuum to reclaim space:
memvid doctor knowledge.mv2 --vacuum

Archive and create new file:

mv knowledge.mv2 archive/knowledge-$(date +%Y%m%d).mv2
memvid create knowledge.mv2

Slow query performance

Symptoms

Queries taking >100ms
Timeouts on large files
High memory usage during search

Diagnosis

# Check file size
ls -lh knowledge.mv2

# Check frame count
memvid stats knowledge.mv2 --json | jq '.frame_count'

# Profile a query
time memvid find knowledge.mv2 --query "test" --json

Solution

Reduce k value for fewer results:

results = mem.find('query', k=5)  # Instead of k=50

Use specific search mode:

# Lexical is faster for exact matches
results = mem.find('exact term', mode='lex')

Add scope filters:

results = mem.find('query', scope='category:docs')

Enable vector compression for smaller index:

memvid put knowledge.mv2 --input docs/ --vector-compression

Split into multiple files for very large datasets:

# Query multiple files in parallel
import asyncio

async def search_all(query):
    files = ['docs.mv2', 'wiki.mv2', 'papers.mv2']
    tasks = [search_file(f, query) for f in files]
    return await asyncio.gather(*tasks)

Import errors in Python

Symptoms

ImportError: cannot import name 'use' from 'memvid_sdk'
ModuleNotFoundError: No module named 'memvid_sdk'
ImportError: libmemvid.so not found

Diagnosis

# Check installation
pip show memvid-sdk

# Check Python version
python --version

# List installed packages
pip list | grep memvid

Solution

Install/reinstall the SDK:
pip install --upgrade memvid-sdk
Check Python version (requires 3.8+):
python3 --version

Use correct virtual environment:

source venv/bin/activate
pip install memvid-sdk

On Apple Silicon, ensure you’re using native Python:

# Check architecture
python -c "import platform; print(platform.machine())"
# Should show 'arm64' on Apple Silicon

Native binding errors in Node.js

Symptoms

Error: Cannot find module '../index.node'
Error: The module was compiled against a different Node.js version
Segmentation fault on import

Diagnosis

# Check Node version
node --version

# Check if native module exists
ls node_modules/@memvid/sdk/*.node

# Check platform
node -e "console.log(process.platform, process.arch)"

Solution

Reinstall with rebuild:

rm -rf node_modules package-lock.json
npm install

Check Node.js version (requires 18+):
nvm use 18 npm rebuild

Install build tools if needed:

# macOS
xcode-select --install

# Ubuntu
sudo apt install build-essential

# Windows
npm install -g windows-build-tools

File corruption after crash

Symptoms

CorruptFile: Invalid header magic bytes
VerificationFailed: Checksum mismatch
File won’t open after system crash

Diagnosis

# Verify file integrity
memvid verify knowledge.mv2 --deep

# Check file header
xxd knowledge.mv2 | head -5

Solution

Run the doctor command:
memvid doctor knowledge.mv2 --vacuum

Rebuild indices:

memvid doctor knowledge.mv2 \
  --rebuild-lex-index \
  --rebuild-vec-index \
  --rebuild-time-index

If recovery fails, restore from backup:

cp /backups/knowledge.mv2 ./knowledge.mv2

Prevent future corruption:
- Always call mem.seal() before exiting
- Use UPS/battery backup for critical systems
- Enable automatic backups

Framework adapter not working

Symptoms

mem.tools returns empty or None
Framework-specific methods missing
Type errors with framework objects

Diagnosis

from memvid_sdk import use

mem = use('langchain', 'knowledge.mv2')
print(f"Tools: {mem.tools}")
print(f"Type: {type(mem.tools)}")

Solution

Install the framework dependency:

# For LangChain
pip install langchain langchain-openai

# For LlamaIndex
pip install llama-index

# For CrewAI
pip install crewai

Use correct adapter name:

# Correct
mem = use('langchain', 'knowledge.mv2')
mem = use('llamaindex', 'knowledge.mv2')
mem = use('crewai', 'knowledge.mv2')

# Incorrect
mem = use('lang-chain', 'knowledge.mv2')  # Wrong!

Check framework version compatibility:
pip show langchain # Check version

Diagnostic Commands

Full Health Check

#!/bin/bash
# health-check.sh

FILE=$1

echo "=== Memvid Health Check ==="
echo "File: $FILE"
echo ""

echo "--- Basic Info ---"
memvid stats "$FILE" --json | jq '.'

echo ""
echo "--- Verification ---"
memvid verify "$FILE" --deep

echo ""
echo "--- Lock Status ---"
lsof "$FILE" 2>/dev/null || echo "No locks detected"

echo ""
echo "--- Ticket Info ---"
memvid tickets list "$FILE"

Performance Profile

import time
from memvid_sdk import use

def profile_operations(filepath: str):
    """Profile common Memvid operations."""

    print(f"Profiling: {filepath}\n")

    mem = use('basic', filepath, read_only=True)

    # Profile search
    start = time.perf_counter()
    for _ in range(10):
        mem.find('test query', k=10)
    search_time = (time.perf_counter() - start) / 10
    print(f"Average search time: {search_time*1000:.2f}ms")

    # Profile ask
    start = time.perf_counter()
    mem.ask('What is this about?')
    ask_time = time.perf_counter() - start
    print(f"Ask time: {ask_time*1000:.2f}ms")

    # Profile timeline
    start = time.perf_counter()
    mem.timeline(limit=100)
    timeline_time = time.perf_counter() - start
    print(f"Timeline time: {timeline_time*1000:.2f}ms")

    print("\n✅ Profiling complete")

profile_operations('knowledge.mv2')

Still Having Issues?

Error Reference

Complete error code documentation

GitHub Issues

Search existing issues or report new ones

Discord Community

Get real-time help from the community

Email Support

Contact our support team

Get Started

Comparisons

Install

Hosting

Architecture

Search & Retrieval

Enrichment

Media Processing

Embeddings

Security & Limits

Performance

CLI

Python SDK

Node.js SDK

Examples & Packages

Testing

Help

Troubleshooting Guide

Quick Diagnosis

Common Issues

”File is locked” when opening

Search returns no results

“CapacityExceeded” error

Slow query performance

Import errors in Python

Native binding errors in Node.js

File corruption after crash

Framework adapter not working

Diagnostic Commands

Full Health Check

Performance Profile

Still Having Issues?

Error Reference

GitHub Issues

Discord Community

Email Support

​Quick Diagnosis

​Common Issues

​”File is locked” when opening

​Search returns no results

​“CapacityExceeded” error

​Slow query performance

​Import errors in Python

​Native binding errors in Node.js

​File corruption after crash

​Framework adapter not working

​Diagnostic Commands

​Full Health Check

​Performance Profile

​Still Having Issues?

Error Reference

GitHub Issues

Discord Community

Email Support

Quick Diagnosis

Common Issues

”File is locked” when opening

Search returns no results

“CapacityExceeded” error

Slow query performance

Import errors in Python

Native binding errors in Node.js

File corruption after crash

Framework adapter not working

Diagnostic Commands

Full Health Check

Performance Profile

Still Having Issues?