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

# Error Code Reference

> Complete reference for all Memvid error codes with causes and solutions

Understanding Memvid error codes helps you quickly diagnose and resolve issues. All errors follow the format `MVXXX` where `XXX` is a three-digit code.

## Error Code Quick Reference

| Code  | Name                 | Category       |
| ----- | -------------------- | -------------- |
| MV001 | CapacityExceeded     | Storage        |
| MV002 | TicketInvalid        | Authentication |
| MV003 | TicketReplay         | Authentication |
| MV004 | LexIndexDisabled     | Index          |
| MV005 | TimeIndexMissing     | Index          |
| MV006 | VerificationFailed   | Integrity      |
| MV007 | FileLocked           | Concurrency    |
| MV008 | ApiKeyRequired       | Authentication |
| MV009 | MemoryAlreadyBound   | Binding        |
| MV010 | FrameNotFound        | Data           |
| MV011 | VecIndexDisabled     | Index          |
| MV012 | CorruptFile          | Integrity      |
| MV013 | IOError              | System         |
| MV014 | VecDimensionMismatch | Index          |
| MV015 | EmbeddingFailed      | Embedding      |
| MV016 | EncryptedFile        | Security       |
| MV999 | InternalError        | System         |

***

## Storage Errors

### MV001 - CapacityExceeded

<Warning>
  Your memory file has exceeded its storage capacity limit.
</Warning>

**Cause:** The `.mv2` file has reached its maximum allowed size based on your plan tier.

**Error Message:**

```
CapacityExceeded: Memory file exceeded capacity limit (current: 1.2GB, limit: 1GB)
```

**Solutions:**

<Tabs>
  <Tab title="Upgrade Plan">
    ```bash theme={null}
    # Sync with control plane to get higher capacity ticket
    memvid tickets sync knowledge.mv2 --memory-id YOUR_MEMORY_ID
    ```
  </Tab>

  <Tab title="Reduce Content">
    ```bash theme={null}
    # Delete old or unused frames
    memvid delete knowledge.mv2 --before "2024-01-01" --yes

    # Vacuum to reclaim space
    memvid doctor knowledge.mv2 --vacuum
    ```
  </Tab>

  <Tab title="Create New File">
    ```bash theme={null}
    # Archive old file and create fresh one
    mv knowledge.mv2 knowledge-archive.mv2
    memvid create knowledge.mv2
    ```
  </Tab>
</Tabs>

**Plan Limits:**

| Plan       | Capacity  |
| ---------- | --------- |
| Free       | 1 GB      |
| Dev        | 10 GB     |
| Pro        | 100 GB    |
| Enterprise | Unlimited |

***

## Authentication Errors

### MV002 - TicketInvalid

<Error>
  The ticket signature is invalid and cannot be verified.
</Error>

**Cause:** The ticket's Ed25519 signature doesn't match, indicating tampering or corruption.

**Error Message:**

```
TicketInvalid: Ticket signature verification failed
```

**Solutions:**

```bash theme={null}
# Re-sync tickets from the control plane
memvid tickets sync knowledge.mv2 --memory-id YOUR_MEMORY_ID

# Or apply a new ticket manually
memvid tickets apply knowledge.mv2 --ticket "eyJ..."
```

<Tip>
  Tickets are cryptographically signed. Never manually edit ticket strings.
</Tip>

***

### MV003 - TicketReplay

<Error>
  This ticket has already been used or has an outdated sequence number.
</Error>

**Cause:** Attempting to apply a ticket with a sequence number less than or equal to the current ticket.

**Error Message:**

```
TicketReplay: Ticket sequence 5 is not greater than current sequence 7
```

**Solutions:**

```bash theme={null}
# Check current ticket info
memvid tickets list knowledge.mv2

# Sync to get the latest ticket
memvid tickets sync knowledge.mv2 --memory-id YOUR_MEMORY_ID
```

***

### MV008 - ApiKeyRequired

<Warning>
  An API key is required for this operation.
</Warning>

**Cause:** Attempting to use a feature that requires authentication without providing an API key.

**Error Message:**

```
ApiKeyRequired: API key required for embedding generation
```

**Solutions:**

<Tabs>
  <Tab title="Node.js SDK">
    ```typescript theme={null}
    import { use } from '@memvid/sdk';

    const mem = await use('basic', 'knowledge.mv2', 'your-api-key');
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from memvid_sdk import use

    mem = use('basic', 'knowledge.mv2', api_key='your-api-key')
    ```
  </Tab>

  <Tab title="Environment Variable">
    ```bash theme={null}
    export MEMVID_API_KEY=your-api-key
    memvid put knowledge.mv2 --input doc.pdf --embeddings
    ```
  </Tab>
</Tabs>

***

## Index Errors

### MV004 - LexIndexDisabled

<Warning>
  Lexical (text) search is not enabled on this memory file.
</Warning>

**Cause:** Attempting to use `mode: lex` or `mode: auto` on a file without lexical indexing.

**Error Message:**

```
LexIndexDisabled: Lexical index not enabled. Use --enable-lex when creating or run doctor.
```

**Solutions:**

```bash theme={null}
# Enable lexical index on existing file
memvid doctor knowledge.mv2 --rebuild-lex-index

# Or use semantic-only search
memvid find knowledge.mv2 --query "machine learning" --mode sem
```

***

### MV005 - TimeIndexMissing

<Warning>
  Time-based queries require a time index that is not present.
</Warning>

**Cause:** Using timeline queries or time filters on a file without time indexing.

**Error Message:**

```
TimeIndexMissing: Time index not found. Rebuild with doctor.
```

**Solutions:**

```bash theme={null}
# Rebuild time index
memvid doctor knowledge.mv2 --rebuild-time-index
```

***

### MV011 - VecIndexDisabled

<Warning>
  Vector (semantic) search is not enabled on this memory file.
</Warning>

**Cause:** Attempting to use `mode: sem` or `mode: auto` without vector indexing.

**Error Message:**

```
VecIndexDisabled: Vector index not enabled. Enable embeddings during ingestion.
```

**Solutions:**

```bash theme={null}
# Rebuild vector index (requires re-ingesting)
memvid doctor knowledge.mv2 --rebuild-vec-index

# Or use lexical-only search
memvid find knowledge.mv2 --query "exact phrase" --mode lex
```

***

### MV014 - VecDimensionMismatch

<Error>
  The embedding dimensions don't match the vector index.
</Error>

**Cause:** Attempting to search or insert with embeddings of a different dimension than what the vector index was built with.

**Error Message:**

```
VecDimensionMismatch: Vector dimension mismatch (expected 384, got 1536)
```

**Solutions:**

1. **Use consistent embedding models**: Ensure you use the same embedding model for ingestion and search.

```bash theme={null}
# Check current embedding dimension
memvid stats knowledge.mv2 --json | jq '.vec_dimension'

# Use matching model for search
memvid find knowledge.mv2 --query "test" --embedding-model bge-small
```

2. **Rebuild with correct embeddings**: If you need to change models, rebuild the vector index.

```bash theme={null}
# Rebuild vector index with new embeddings
memvid doctor knowledge.mv2 --rebuild-vec-index --embedding-model openai
```

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    // Ensure consistent embedder usage
    const mem = await use('basic', 'knowledge.mv2');

    // Use same model for put and find
    await mem.put({ text: 'content', embeddingModel: 'bge-small' });
    await mem.find('query', { embeddingModel: 'bge-small' });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Ensure consistent embedder usage
    mem = use('basic', 'knowledge.mv2')

    # Use same model for put and find
    mem.put(text='content', embedding_model='bge-small')
    mem.find('query', embedding_model='bge-small')
    ```
  </Tab>
</Tabs>

***

## Integrity Errors

### MV006 - VerificationFailed

<Error>
  File integrity verification failed.
</Error>

**Cause:** The file's checksums don't match, indicating corruption.

**Error Message:**

```
VerificationFailed: Header checksum mismatch (expected: abc123, got: def456)
```

**Solutions:**

```bash theme={null}
# Run deep verification to identify issues
memvid verify knowledge.mv2 --deep

# Attempt repair
memvid doctor knowledge.mv2 --rebuild-lex-index --rebuild-vec-index

# If repair fails, restore from backup
cp knowledge-backup.mv2 knowledge.mv2
```

<Warning>
  Always maintain backups of important memory files. Corruption can occur from disk errors, interrupted writes, or software bugs.
</Warning>

***

### MV012 - CorruptFile

<Error>
  The memory file is corrupt and cannot be read.
</Error>

**Cause:** Severe file corruption preventing basic operations.

**Error Message:**

```
CorruptFile: Invalid header magic bytes
```

**Solutions:**

```bash theme={null}
# Try doctor repair
memvid doctor knowledge.mv2 --vacuum

# If that fails, restore from backup
cp /backups/knowledge.mv2 ./knowledge.mv2
```

***

### MV013 - IOError

<Error>
  An I/O operation failed.
</Error>

**Cause:** File system operations failed, such as file not found, permission denied, or disk full.

**Error Message:**

```
IOError: I/O error: No such file or directory (os error 2)
```

**Solutions:**

```bash theme={null}
# Check if file exists
ls -la knowledge.mv2

# Check disk space
df -h .

# Check file permissions
ls -la knowledge.mv2

# Fix permissions if needed
chmod 644 knowledge.mv2
```

<Tip>
  Ensure the file path is correct and you have read/write permissions to the directory.
</Tip>

***

## Concurrency Errors

### MV007 - FileLocked

<Warning>
  The file is locked by another process.
</Warning>

**Cause:** Another process has an exclusive write lock on the file.

**Error Message:**

```
FileLocked: File is locked by another process (PID: 12345)
```

**Solutions:**

```bash theme={null}
# Find the locking process
lsof knowledge.mv2

# Wait for it to finish, or kill if stuck
kill 12345

# Open in read-only mode if you only need to query
```

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    const mem = await use('basic', 'knowledge.mv2', { readOnly: true });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mem = use('basic', 'knowledge.mv2', read_only=True)
    ```
  </Tab>
</Tabs>

***

## Data Errors

### MV009 - MemoryAlreadyBound

<Warning>
  This memory file is already bound to a different memory ID.
</Warning>

**Cause:** Attempting to bind a file that's already associated with another memory in the control plane.

**Error Message:**

```
MemoryAlreadyBound: File is bound to memory_id: abc-123, cannot rebind to def-456
```

**Solutions:**

```bash theme={null}
# Check current binding
memvid info knowledge.mv2

# Unbind if intentional
memvid unbind knowledge.mv2

# Then bind to new memory
memvid tickets sync knowledge.mv2 --memory-id NEW_MEMORY_ID
```

***

### MV010 - FrameNotFound

<Warning>
  The requested frame does not exist.
</Warning>

**Cause:** Referencing a frame ID that doesn't exist in the file.

**Error Message:**

```
FrameNotFound: Frame with id 999 not found
```

**Solutions:**

```bash theme={null}
# List available frames
memvid timeline knowledge.mv2 --limit 100

# Check stats for frame count
memvid stats knowledge.mv2
```

***

## Embedding Errors

### MV015 - EmbeddingFailed

<Error>
  Embedding generation failed.
</Error>

**Cause:** The embedding runtime is unavailable, the API key is missing or invalid, or the model is not accessible.

**Error Message:**

```
EmbeddingFailed: Failed to generate embeddings: API key not configured for openai
```

**Solutions:**

1. **Check API key configuration**:

```bash theme={null}
# Set environment variable
export OPENAI_API_KEY=sk-...

# Or use local embeddings (no API key needed)
memvid put knowledge.mv2 --input doc.pdf --embedding-model bge-small
```

2. **Use local embeddings**:

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    import { use, LOCAL_EMBEDDING_MODELS } from '@memvid/sdk';

    const mem = await use('basic', 'knowledge.mv2');

    // Use local model - no API key required
    await mem.put({
      text: 'content',
      enableEmbedding: true,
      embeddingModel: LOCAL_EMBEDDING_MODELS.BGE_SMALL
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from memvid_sdk import use

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

    # Use local model - no API key required
    mem.put(
        text='content',
        enable_embedding=True,
        embedding_model='bge-small'
    )
    ```
  </Tab>
</Tabs>

3. **Check network connectivity** if using external providers:

```bash theme={null}
# Test API connectivity
curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
```

<Tip>
  Local embedding models (BGE, Nomic, GTE) work offline and don't require API keys. They're bundled with the SDK.
</Tip>

***

## Security Errors

### MV016 - EncryptedFile

<Warning>
  The file is encrypted and requires decryption.
</Warning>

**Cause:** Attempting to open an encrypted `.mv2e` capsule without providing the password.

**Error Message:**

```
EncryptedFile: File is encrypted. Use unlock() with password to decrypt.
```

**Solutions:**

1. **Decrypt the file**:

```bash theme={null}
# Decrypt to .mv2
memvid unlock knowledge.mv2e --password "your-password"
```

2. **Open encrypted file in SDKs**:

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    import { unlock } from '@memvid/sdk';

    // Decrypt first
    const decryptedPath = await unlock('knowledge.mv2e', {
      password: 'your-password'
    });

    // Then open normally
    const mem = await use('basic', decryptedPath);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from memvid_sdk import unlock, use

    # Decrypt first
    decrypted_path = unlock('knowledge.mv2e', password='your-password')

    # Then open normally
    mem = use('basic', decrypted_path)
    ```
  </Tab>
</Tabs>

<Warning>
  Never commit passwords to version control. Use environment variables or secure secret management.
</Warning>

***

## System Errors

### MV999 - InternalError

<Error>
  An unexpected internal error occurred.
</Error>

**Cause:** Unexpected condition in the Memvid engine.

**Error Message:**

```
InternalError: Unexpected condition in segment builder: index out of bounds
```

**Solutions:**

1. **Report the bug:** Include the full error message and stack trace
2. **Try again:** Some transient errors resolve on retry
3. **Check disk space:** Ensure sufficient storage available
4. **Update Memvid:** Upgrade to the latest version

```bash theme={null}
# Check version
memvid --version

# Update
cargo install memvid-cli --force
# or
pip install --upgrade memvid-sdk
```

***

## SDK Error Handling

### Python

```python theme={null}
from memvid_sdk import (
    use,
    MemvidError,
    CapacityExceededError,      # MV001
    TicketInvalidError,          # MV002
    TicketReplayError,           # MV003
    LexIndexDisabledError,       # MV004
    TimeIndexMissingError,       # MV005
    VerifyFailedError,           # MV006
    LockedError,                 # MV007
    ApiKeyRequiredError,         # MV008
    MemoryAlreadyBoundError,     # MV009
    FrameNotFoundError,          # MV010
    VecIndexDisabledError,       # MV011
    CorruptFileError,            # MV012
    IOError,                     # MV013
    VecDimensionMismatchError,   # MV014
    EmbeddingFailedError,        # MV015
    EncryptedFileError,          # MV016
)

try:
    mem = use('basic', 'knowledge.mv2')
    mem.put({"title": "Doc", "text": "Content...", "label": "test"})
except CapacityExceededError as e:
    print(f"Storage full: {e.details}")
except LockedError:
    print("File in use, retrying in read-only mode...")
    mem = use('basic', 'knowledge.mv2', read_only=True)
except VecDimensionMismatchError as e:
    print(f"Embedding dimension mismatch: {e.details}")
except EmbeddingFailedError as e:
    print(f"Embedding failed: {e.details}")
except EncryptedFileError:
    print("File is encrypted, use unlock() first")
except MemvidError as e:
    print(f"Memvid error [{e.code}]: {e.message}")
```

### Node.js

```typescript theme={null}
import {
  use,
  MemvidError,
  CapacityExceededError,      // MV001
  TicketInvalidError,          // MV002
  TicketReplayError,           // MV003
  LexIndexDisabledError,       // MV004
  TimeIndexMissingError,       // MV005
  VerifyFailedError,           // MV006
  LockedError,                 // MV007
  ApiKeyRequiredError,         // MV008
  MemoryAlreadyBoundError,     // MV009
  FrameNotFoundError,          // MV010
  VecIndexDisabledError,       // MV011
  CorruptFileError,            // MV012
  IOError,                     // MV013
  VecDimensionMismatchError,   // MV014
  EmbeddingFailedError,        // MV015
  EncryptedFileError,          // MV016
} from '@memvid/sdk';

try {
  const mem = await use('basic', 'knowledge.mv2');
  await mem.put({ title: 'Doc', text: 'Content...', label: 'test' });
} catch (error) {
  if (error instanceof CapacityExceededError) {
    console.error('Storage full:', error.details);
  } else if (error instanceof LockedError) {
    console.error('File locked, try read-only mode');
  } else if (error instanceof VecDimensionMismatchError) {
    console.error('Embedding dimension mismatch:', error.details);
  } else if (error instanceof EmbeddingFailedError) {
    console.error('Embedding failed:', error.details);
  } else if (error instanceof EncryptedFileError) {
    console.error('File is encrypted, use unlock() first');
  } else if (error instanceof MemvidError) {
    console.error(`Error [${error.code}]: ${error.message}`);
  } else {
    throw error;
  }
}
```

***

## Getting Help

<CardGroup cols={2}>
  <Card title="Troubleshooting Guide" icon="wrench" href="/errors/troubleshooting">
    Step-by-step solutions for common issues
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/memvid/memvid/issues">
    Report bugs or request features
  </Card>

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

  <Card title="FAQ" icon="question" href="/faq/general">
    Frequently asked questions
  </Card>
</CardGroup>