Error Code Reference

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

Your memory file has exceeded its storage capacity limit.

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:

Upgrade Plan
Reduce Content
Create New File

# Sync with control plane to get higher capacity ticket
memvid tickets sync knowledge.mv2 --memory-id YOUR_MEMORY_ID

# Delete old or unused frames
memvid delete knowledge.mv2 --before "2024-01-01" --yes

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

# Archive old file and create fresh one
mv knowledge.mv2 knowledge-archive.mv2
memvid create knowledge.mv2

Plan Limits:

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

Authentication Errors

MV002 - TicketInvalid

Cause: The ticket’s Ed25519 signature doesn’t match, indicating tampering or corruption. Error Message:

TicketInvalid: Ticket signature verification failed

Solutions:

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

Tickets are cryptographically signed. Never manually edit ticket strings.

MV003 - TicketReplay

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:

# 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

An API key is required for this operation.

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

ApiKeyRequired: API key required for embedding generation

Solutions:

Node.js SDK
Python SDK
Environment Variable

import { use } from '@memvid/sdk';

const mem = await use('basic', 'knowledge.mv2', 'your-api-key');

from memvid_sdk import use

mem = use('basic', 'knowledge.mv2', api_key='your-api-key')

export MEMVID_API_KEY=your-api-key
memvid put knowledge.mv2 --input doc.pdf --embeddings

Index Errors

MV004 - LexIndexDisabled

Lexical (text) search is not enabled on this memory file.

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:

# 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

Time-based queries require a time index that is not present.

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

TimeIndexMissing: Time index not found. Rebuild with doctor.

Solutions:

# Rebuild time index
memvid doctor knowledge.mv2 --rebuild-time-index

MV011 - VecIndexDisabled

Vector (semantic) search is not enabled on this memory file.

Cause: Attempting to use mode: sem or mode: auto without vector indexing. Error Message:

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

Solutions:

# 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

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:

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

# 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

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

# Rebuild vector index with new embeddings
memvid doctor knowledge.mv2 --rebuild-vec-index --embedding-model openai

Node.js
Python

// 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' });

# 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')

Integrity Errors

MV006 - VerificationFailed

Cause: The file’s checksums don’t match, indicating corruption. Error Message:

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

Solutions:

# 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

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

MV012 - CorruptFile

Cause: Severe file corruption preventing basic operations. Error Message:

CorruptFile: Invalid header magic bytes

Solutions:

# Try doctor repair
memvid doctor knowledge.mv2 --vacuum

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

MV013 - IOError

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:

# 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

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

Concurrency Errors

MV007 - FileLocked

The file is locked by another process.

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

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

Solutions:

# 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

Node.js
Python

const mem = await use('basic', 'knowledge.mv2', { readOnly: true });

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

Data Errors

MV009 - MemoryAlreadyBound

This memory file is already bound to a different memory ID.

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:

# 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

The requested frame does not exist.

Cause: Referencing a frame ID that doesn’t exist in the file. Error Message:

FrameNotFound: Frame with id 999 not found

Solutions:

# List available frames
memvid timeline knowledge.mv2 --limit 100

# Check stats for frame count
memvid stats knowledge.mv2

Embedding Errors

MV015 - EmbeddingFailed

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:

Check API key configuration:

# 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

Use local embeddings:

Node.js
Python

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
});

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'
)

Check network connectivity if using external providers:

# Test API connectivity
curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

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

Security Errors

MV016 - EncryptedFile

The file is encrypted and requires decryption.

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:

Decrypt the file:

# Decrypt to .mv2
memvid unlock knowledge.mv2e --password "your-password"

Open encrypted file in SDKs:

Node.js
Python

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);

from memvid_sdk import unlock, use

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

# Then open normally
mem = use('basic', decrypted_path)

Never commit passwords to version control. Use environment variables or secure secret management.

System Errors

MV999 - InternalError

Cause: Unexpected condition in the Memvid engine. Error Message:

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

Solutions:

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

# Check version
memvid --version

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

SDK Error Handling

Python

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

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

Troubleshooting Guide

Step-by-step solutions for common issues

GitHub Issues

Report bugs or request features

Discord Community

Get help from the community

FAQ

Frequently asked questions

​Error Code Quick Reference

​Storage Errors

​MV001 - CapacityExceeded

​Authentication Errors

​MV002 - TicketInvalid

​MV003 - TicketReplay

​MV008 - ApiKeyRequired

​Index Errors

​MV004 - LexIndexDisabled

​MV005 - TimeIndexMissing

​MV011 - VecIndexDisabled

​MV014 - VecDimensionMismatch

​Integrity Errors

​MV006 - VerificationFailed

​MV012 - CorruptFile

​MV013 - IOError

​Concurrency Errors

​MV007 - FileLocked

​Data Errors

​MV009 - MemoryAlreadyBound

​MV010 - FrameNotFound

​Embedding Errors

​MV015 - EmbeddingFailed

​Security Errors

​MV016 - EncryptedFile

​System Errors

​MV999 - InternalError

​SDK Error Handling

​Python

​Node.js

​Getting Help

Troubleshooting Guide

GitHub Issues

Discord Community

FAQ

Error Code Quick Reference

Storage Errors

MV001 - CapacityExceeded

Authentication Errors

MV002 - TicketInvalid

MV003 - TicketReplay

MV008 - ApiKeyRequired

Index Errors

MV004 - LexIndexDisabled

MV005 - TimeIndexMissing

MV011 - VecIndexDisabled

MV014 - VecDimensionMismatch

Integrity Errors

MV006 - VerificationFailed

MV012 - CorruptFile

MV013 - IOError

Concurrency Errors

MV007 - FileLocked

Data Errors

MV009 - MemoryAlreadyBound

MV010 - FrameNotFound

Embedding Errors

MV015 - EmbeddingFailed

Security Errors

MV016 - EncryptedFile

System Errors

MV999 - InternalError

SDK Error Handling

Python

Node.js

Getting Help