Common Errors - AgentFront

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

FAQ

Frequently asked questions

Error Handling

Programmatic error handling

​VectoriaNotInitializedError

​Cause

​Example

​Solution

​ConfigurationError

​Cause

​Example

​Solution

​DocumentValidationError

​Cause

​Example

​Solution

​DocumentExistsError

​Cause

​Example

​Solution

​DuplicateDocumentError

​Cause

​Example

​Solution

​QueryValidationError

​Cause

​Example

​Solution

​StorageError

​Cause

​Example

​Solution

​EmbeddingError

​Cause

​Example

​Solution

​Error Recovery Pattern

​Related

FAQ

Error Handling

VectoriaNotInitializedError

Cause

Example

Solution

ConfigurationError

Cause

Example

Solution

DocumentValidationError

Cause

Example

Solution

DocumentExistsError

Cause

Example

Solution

DuplicateDocumentError

Cause

Example

Solution

QueryValidationError

Cause

Example

Solution

StorageError

Cause

Example

Solution

EmbeddingError

Cause

Example

Solution

Error Recovery Pattern

Related