Skip to main content
All VectoriaDB errors extend VectoriaError and include machine-readable code values.

​
Error Types

ErrorCodeDescription
VectoriaNotInitializedErrorNOT_INITIALIZEDCall initialize() first
DocumentValidationErrorDOCUMENT_VALIDATION_ERRORInvalid document data
DocumentNotFoundErrorDOCUMENT_NOT_FOUNDDocument ID doesn’t exist
DocumentExistsErrorDOCUMENT_EXISTSDocument ID already exists
DuplicateDocumentErrorDUPLICATE_DOCUMENTDuplicate in batch
QueryValidationErrorQUERY_VALIDATION_ERRORInvalid search query
EmbeddingErrorEMBEDDING_ERRORModel embedding failed
StorageErrorSTORAGE_ERRORStorage operation failed
ConfigurationErrorCONFIGURATION_ERRORInvalid config

​
Importing Errors

import {
  VectoriaError,
  VectoriaNotInitializedError,
  DocumentValidationError,
  DocumentNotFoundError,
  DocumentExistsError,
  DuplicateDocumentError,
  QueryValidationError,
  EmbeddingError,
  StorageError,
  ConfigurationError,
} from 'vectoriadb';

​
VectoriaError

Base class for all VectoriaDB errors. 
class VectoriaError extends Error {
  readonly code: string;

  constructor(message: string, code: string);
}

​
VectoriaNotInitializedError

Thrown when operations are attempted before initialization. 
class VectoriaNotInitializedError extends VectoriaError {
  constructor(operation: string);
}

​
Example

try {
  await db.add('id', 'text', metadata);
} catch (error) {
  if (error instanceof VectoriaNotInitializedError) {
    await db.initialize();
    await db.add('id', 'text', metadata);
  }
}

​
DocumentValidationError

Thrown when document validation fails. 
class DocumentValidationError extends VectoriaError {
  readonly documentId?: string;

  constructor(message: string, documentId?: string);
}

​
DocumentNotFoundError

Thrown when a document ID doesn’t exist. 
class DocumentNotFoundError extends VectoriaError {
  readonly documentId: string;

  constructor(documentId: string);
}

​
DocumentExistsError

Thrown when adding a document with an existing ID. 
class DocumentExistsError extends VectoriaError {
  readonly documentId: string;

  constructor(documentId: string);
}

​
DuplicateDocumentError

Thrown when duplicates are found in batch operations. 
class DuplicateDocumentError extends VectoriaError {
  readonly documentId: string;
  readonly context: 'batch' | 'existing';

  constructor(documentId: string, context: 'batch' | 'existing');
}

​
QueryValidationError

Thrown when search parameters are invalid. 
class QueryValidationError extends VectoriaError {
  constructor(message: string);
}

​
EmbeddingError

Thrown when embedding generation fails. 
class EmbeddingError extends VectoriaError {
  readonly details?: any;

  constructor(message: string, details?: any);
}

​
StorageError

Thrown when storage operations fail. 
class StorageError extends VectoriaError {
  readonly originalError?: Error;

  constructor(message: string, originalError?: Error);
}

​
ConfigurationError

Thrown when configuration is invalid. 
class ConfigurationError extends VectoriaError {
  constructor(message: string);
}

​
Error Handling Pattern

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

  if (error instanceof DocumentValidationError) {
    console.warn(`Invalid document: ${error.documentId}`);
    return;
  }

  if (error instanceof VectoriaError) {
    console.error(`VectoriaDB error [${error.code}]:`, error.message);
    return;
  }

  throw error; // Re-throw unexpected errors
}

Common Errors

Error solutions

FAQ

Frequently asked questions