Common Errors

Solutions for common VectoriaDB errors

This page covers common errors and their solutions.

All VectoriaDB errors extend VectoriaError and include a machine-readable code property for programmatic handling.

VectoriaNotInitializedError

Code: NOT_INITIALIZED

Cause

You attempted to use VectoriaDB before calling initialize().

Example

src/error-not-initialized.ts

const db = new VectoriaDB();
await db.add('id', 'text', metadata); // Error: NOT_INITIALIZED

Solution

Always call initialize() before any operation:

src/fix-not-initialized.ts

const db = new VectoriaDB();
await db.initialize(); // Required!
await db.add('id', 'text', metadata); // Now works

initialize() is idempotent - calling it multiple times is safe and only runs once.

---

ConfigurationError

Code: CONFIGURATION_ERROR

Cause

Invalid configuration options were passed to the constructor.

Example

src/error-configuration.ts

const db = new VectoriaDB({
  maxDocuments: -1, // Error: Invalid value
});

Solution

Check that all configuration values are valid:

src/fix-configuration.ts

const db = new VectoriaDB({
  maxDocuments: 100000,    // Must be positive
  maxBatchSize: 1000,      // Must be positive
  defaultTopK: 10,         // Must be positive
  defaultSimilarityThreshold: 0.3, // Must be 0-1
});

---

DocumentValidationError

Code: DOCUMENT_VALIDATION_ERROR

Cause

A document failed validation. Common issues:

• Missing required fields (id, text, metadata)
• Empty id or text
• Text exceeds maxDocumentSize
• Invalid metadata structure

Example

src/error-validation.ts

await db.add('', 'text', metadata); // Error: Empty ID
await db.add('id', '', metadata);   // Error: Empty text

Solution

Ensure all documents have valid data:

src/fix-validation.ts

// Validate before adding
function validateDocument(doc: { id: string; text: string }) {
  if (!doc.id?.trim()) throw new Error('ID required');
  if (!doc.text?.trim()) throw new Error('Text required');
  if (doc.text.length > 1000000) throw new Error('Text too long');
}

validateDocument(doc);
await db.add(doc.id, doc.text, doc.metadata);

---

DocumentExistsError

Code: DOCUMENT_EXISTS

Cause

You attempted to add a document with an ID that already exists.

Example

src/error-exists.ts

await db.add('user:1', 'First user', metadata);
await db.add('user:1', 'Another user', metadata); // Error: DOCUMENT_EXISTS

Solution

Check if document exists before adding, or use update():

src/fix-exists.ts

// Option 1: Check first
if (!db.has('user:1')) {
  await db.add('user:1', 'User text', metadata);
}

// Option 2: Use update for upsert behavior
await db.update('user:1', {
  text: 'Updated text',
  metadata,
});

---

DuplicateDocumentError

Code: DUPLICATE_DOCUMENT

Cause

A batch operation contained duplicate document IDs.

Example

src/error-duplicate.ts

await db.addMany([
  { id: 'doc1', text: 'Text 1', metadata: m1 },
  { id: 'doc1', text: 'Text 2', metadata: m2 }, // Error: Duplicate ID
]);

Solution

Deduplicate documents before batch operations:

src/fix-duplicate.ts

function deduplicateById<T extends { id: string }>(docs: T[]): T[] {
  const seen = new Set<string>();
  return docs.filter((doc) => {
    if (seen.has(doc.id)) return false;
    seen.add(doc.id);
    return true;
  });
}

const uniqueDocs = deduplicateById(documents);
await db.addMany(uniqueDocs);

---

QueryValidationError

Code: QUERY_VALIDATION_ERROR

Cause

Invalid search parameters were provided.

Example

src/error-query.ts

await db.search(query, { topK: -1 });     // Error: Invalid topK
await db.search(query, { threshold: 2 }); // Error: Invalid threshold
await db.search('');                       // Error: Empty query

Solution

Validate search options:

src/fix-query.ts

await db.search(query, {
  topK: Math.max(1, topK),           // Must be positive
  threshold: Math.min(1, Math.max(0, threshold)), // Must be 0-1
});

---

StorageError

Code: STORAGE_ERROR

Cause

A storage operation failed. Common issues:

• Disk full or no write permission
• Redis connection failed
• Corrupted cache file

Example

src/error-storage.ts

await db.saveToStorage(); // Error: Permission denied

Solution

Handle storage errors gracefully:

src/fix-storage.ts

import { StorageError } from 'vectoriadb';

try {
  await db.saveToStorage();
} catch (error) {
  if (error instanceof StorageError) {
    console.warn('Storage failed, continuing in-memory only');
    // Application continues without persistence
  } else {
    throw error;
  }
}

---

EmbeddingError

Code: EMBEDDING_ERROR

Cause

The embedding model failed to generate embeddings. Common issues:

• Model not loaded (not initialized)
• Out of memory
• Invalid input text

Example

src/error-embedding.ts

// Very long text might cause memory issues
await db.add('id', veryLongText, metadata); // Error: EMBEDDING_ERROR

Solution

Handle embedding errors and validate input:

src/fix-embedding.ts

import { EmbeddingError } from 'vectoriadb';

try {
  await db.add('id', text, metadata);
} catch (error) {
  if (error instanceof EmbeddingError) {
    console.error('Embedding failed:', error.message);
    // Log for debugging, skip document
  } else {
    throw error;
  }
}

---

Error Recovery Pattern

Use this pattern for robust error handling:

src/error-recovery.ts

import {
  VectoriaError,
  VectoriaNotInitializedError,
  DocumentValidationError,
  StorageError,
} from 'vectoriadb';

async function safeOperation() {
  try {
    await db.addMany(documents);
    await db.saveToStorage();
  } catch (error) {
    if (error instanceof VectoriaNotInitializedError) {
      await db.initialize();
      return safeOperation(); // Retry
    }

    if (error instanceof DocumentValidationError) {
      console.warn(`Skipping invalid document: ${error.documentId}`);
      const valid = documents.filter((d) => d.id !== error.documentId);
      await db.addMany(valid);
      return;
    }

    if (error instanceof StorageError) {
      console.warn('Storage unavailable, continuing without persistence');
      return;
    }

    throw error; // Re-throw unexpected errors
  }
}

Related

FAQ

Frequently asked questions

Error Handling

Programmatic error handling