> ## 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 Guide

> Step-by-step solutions for common Memvid issues

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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Symptoms">
    * `FileLocked: File is locked by another process`
    * Operations hang indefinitely
    * Cannot open file in Python/Node.js
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # Find process holding the lock
    lsof knowledge.mv2

    # Check for zombie processes
    ps aux | grep memvid
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Wait for the other process to finish**
    2. **Kill the blocking process** (if stuck):
       ```bash theme={null}
       kill -9 <PID>
       ```
    3. **Open in read-only mode**:
       ```python theme={null}
       mem = use('basic', 'knowledge.mv2', read_only=True)
       ```
    4. **Check for crashed processes** - if a process crashed while holding a lock, restart your terminal/IDE
  </Accordion>
</AccordionGroup>

***

### Search returns no results

<AccordionGroup>
  <Accordion title="Symptoms">
    * `mem.find()` returns empty results
    * CLI search shows "0 results"
    * Expected documents not appearing
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Verify content exists**:
       ```bash theme={null}
       memvid timeline knowledge.mv2 --limit 10
       ```

    2. **Check search mode** - try `lex` for exact matches, `sem` for semantic:
       ```python theme={null}
       # Exact keyword match
       results = mem.find('exact phrase', mode='lex')

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

    3. **Rebuild indices** if they're corrupted:
       ```bash theme={null}
       memvid doctor knowledge.mv2 --rebuild-lex-index --rebuild-vec-index
       ```

    4. **Check embeddings were enabled** during ingestion:
       ```bash theme={null}
       memvid put knowledge.mv2 --input doc.pdf --embeddings
       ```
  </Accordion>
</AccordionGroup>

***

### "CapacityExceeded" error

<AccordionGroup>
  <Accordion title="Symptoms">
    * `CapacityExceeded: Memory file exceeded capacity limit`
    * `put()` operations fail
    * Cannot add new content
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # Check current usage
    memvid stats knowledge.mv2 --json | jq '.size_bytes, .capacity_bytes'

    # Check ticket info
    memvid tickets list knowledge.mv2
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Upgrade your plan** for more capacity:
       ```bash theme={null}
       memvid tickets sync knowledge.mv2 --memory-id YOUR_ID
       ```

    2. **Delete old content**:
       ```bash theme={null}
       memvid delete knowledge.mv2 --before "2024-01-01" --yes
       ```

    3. **Vacuum to reclaim space**:
       ```bash theme={null}
       memvid doctor knowledge.mv2 --vacuum
       ```

    4. **Archive and create new file**:
       ```bash theme={null}
       mv knowledge.mv2 archive/knowledge-$(date +%Y%m%d).mv2
       memvid create knowledge.mv2
       ```
  </Accordion>
</AccordionGroup>

***

### Slow query performance

<AccordionGroup>
  <Accordion title="Symptoms">
    * Queries taking >100ms
    * Timeouts on large files
    * High memory usage during search
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Reduce `k` value** for fewer results:
       ```python theme={null}
       results = mem.find('query', k=5)  # Instead of k=50
       ```

    2. **Use specific search mode**:
       ```python theme={null}
       # Lexical is faster for exact matches
       results = mem.find('exact term', mode='lex')
       ```

    3. **Add scope filters**:
       ```python theme={null}
       results = mem.find('query', scope='category:docs')
       ```

    4. **Enable vector compression** for smaller index:
       ```bash theme={null}
       memvid put knowledge.mv2 --input docs/ --vector-compression
       ```

    5. **Split into multiple files** for very large datasets:
       ```python theme={null}
       # 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)
       ```
  </Accordion>
</AccordionGroup>

***

### Import errors in Python

<AccordionGroup>
  <Accordion title="Symptoms">
    * `ImportError: cannot import name 'use' from 'memvid_sdk'`
    * `ModuleNotFoundError: No module named 'memvid_sdk'`
    * `ImportError: libmemvid.so not found`
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # Check installation
    pip show memvid-sdk

    # Check Python version
    python --version

    # List installed packages
    pip list | grep memvid
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Install/reinstall the SDK**:
       ```bash theme={null}
       pip install --upgrade memvid-sdk
       ```

    2. **Check Python version** (requires 3.8+):
       ```bash theme={null}
       python3 --version
       ```

    3. **Use correct virtual environment**:
       ```bash theme={null}
       source venv/bin/activate
       pip install memvid-sdk
       ```

    4. **On Apple Silicon**, ensure you're using native Python:
       ```bash theme={null}
       # Check architecture
       python -c "import platform; print(platform.machine())"
       # Should show 'arm64' on Apple Silicon
       ```
  </Accordion>
</AccordionGroup>

***

### Native binding errors in Node.js

<AccordionGroup>
  <Accordion title="Symptoms">
    * `Error: Cannot find module '../index.node'`
    * `Error: The module was compiled against a different Node.js version`
    * Segmentation fault on import
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # 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)"
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Reinstall with rebuild**:
       ```bash theme={null}
       rm -rf node_modules package-lock.json
       npm install
       ```

    2. **Check Node.js version** (requires 18+):
       ```bash theme={null}
       nvm use 18
       npm rebuild
       ```

    3. **Install build tools** if needed:
       ```bash theme={null}
       # macOS
       xcode-select --install

       # Ubuntu
       sudo apt install build-essential

       # Windows
       npm install -g windows-build-tools
       ```
  </Accordion>
</AccordionGroup>

***

### File corruption after crash

<AccordionGroup>
  <Accordion title="Symptoms">
    * `CorruptFile: Invalid header magic bytes`
    * `VerificationFailed: Checksum mismatch`
    * File won't open after system crash
  </Accordion>

  <Accordion title="Diagnosis">
    ```bash theme={null}
    # Verify file integrity
    memvid verify knowledge.mv2 --deep

    # Check file header
    xxd knowledge.mv2 | head -5
    ```
  </Accordion>

  <Accordion title="Solution">
    1. **Run the doctor command**:
       ```bash theme={null}
       memvid doctor knowledge.mv2 --vacuum
       ```

    2. **Rebuild indices**:
       ```bash theme={null}
       memvid doctor knowledge.mv2 \
         --rebuild-lex-index \
         --rebuild-vec-index \
         --rebuild-time-index
       ```

    3. **If recovery fails**, restore from backup:
       ```bash theme={null}
       cp /backups/knowledge.mv2 ./knowledge.mv2
       ```

    4. **Prevent future corruption**:
       * Always call `mem.seal()` before exiting
       * Use UPS/battery backup for critical systems
       * Enable automatic backups
  </Accordion>
</AccordionGroup>

***

### Framework adapter not working

<AccordionGroup>
  <Accordion title="Symptoms">
    * `mem.tools` returns empty or None
    * Framework-specific methods missing
    * Type errors with framework objects
  </Accordion>

  <Accordion title="Diagnosis">
    ```python theme={null}
    from memvid_sdk import use

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

  <Accordion title="Solution">
    1. **Install the framework dependency**:
       ```bash theme={null}
       # For LangChain
       pip install langchain langchain-openai

       # For LlamaIndex
       pip install llama-index

       # For CrewAI
       pip install crewai
       ```

    2. **Use correct adapter name**:
       ```python theme={null}
       # Correct
       mem = use('langchain', 'knowledge.mv2')
       mem = use('llamaindex', 'knowledge.mv2')
       mem = use('crewai', 'knowledge.mv2')

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

    3. **Check framework version compatibility**:
       ```bash theme={null}
       pip show langchain  # Check version
       ```
  </Accordion>
</AccordionGroup>

***

## Diagnostic Commands

### Full Health Check

```bash theme={null}
#!/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

```python theme={null}
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?

<CardGroup cols={2}>
  <Card title="Error Reference" icon="book" href="/errors/reference">
    Complete error code documentation
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/memvid/memvid/issues">
    Search existing issues or report new ones
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/2mynS7fcK7">
    Get real-time help from the community
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@memvid.com">
    Contact our support team
  </Card>
</CardGroup>