mastra-ai/mastra · error · MastraError

Vectors array cannot be empty

Error message

Vectors array cannot be empty

What it means

This error is thrown by validateUpsertInput when a vector store's upsert() receives an empty, null, or undefined vectors array. The library refuses the call because an upsert with no vectors is always a caller mistake and would silently do nothing.

Source

Thrown at packages/core/src/vector/validation.ts:28

/**
 * Validates upsert input parameters
 *
 * @param storeName - Name of the vector store (e.g., 'PG', 'CHROMA')
 * @param vectors - Array of vectors to upsert
 * @param metadata - Optional metadata array
 * @param ids - Optional ids array
 * @throws MastraError if validation fails
 */
export function validateUpsertInput(
  storeName: string,
  vectors: number[][] | undefined | null,
  metadata?: Record<string, any>[] | null,
  ids?: string[] | null,
): void {
  // Validate vectors array is not empty
  if (!vectors || vectors.length === 0) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'UPSERT', 'EMPTY_VECTORS'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {
        message: 'Vectors array cannot be empty',
      },
    });
  }

  // Validate metadata length matches vectors length (skip if metadata is empty/not provided)
  if (metadata && metadata.length > 0 && metadata.length !== vectors.length) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'UPSERT', 'METADATA_LENGTH_MISMATCH'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {
        message: 'Metadata array length must match vectors array length',
        vectorsLength: vectors.length,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the vectors array contains at least one number[] before calling upsert
2. Check the code that produces the vectors (embedding call, batch loop) for early-exit or empty-filter bugs
3. Guard the call site: skip or throw your own clearer error when vectors.length === 0

Example fix

// before
await store.upsert({ indexName: 'docs', vectors: [] });
// after
if (vectors.length === 0) throw new Error('No vectors to upsert');
await store.upsert({ indexName: 'docs', vectors });

if (!Array.isArray(vectors) || vectors.length === 0) {
  throw new Error('upsert requires at least one vector');
}

function hasVectors(v: unknown): v is number[][] {
  return Array.isArray(v) && v.length > 0;
}

try {
  await store.upsert({ indexName, vectors });
} catch (e) {
  if (e instanceof MastraError && e.id.includes('EMPTY_VECTORS')) {
    console.warn('Nothing to upsert, skipping');
    return;
  }
  throw e;
}

When it happens

Trigger: Calling store.upsert({ indexName, vectors: [] }), passing null/undefined vectors, or building the vectors array from a filter/transformation that produced zero results.

Common situations: An embedding batch came back empty (e.g. empty input documents list), a variable was initialized as [] and never filled, or query results feeding the upsert were filtered to nothing.

Related errors

• Metadata array length must match vectors array length
• IDs array length must match vectors array length
• Vector at index ${i} is null or undefined
• Vector contains invalid value (null, undefined, NaN, or Infi
• topK must be a positive integer

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/a487fc33f84bc4bb. Report an issue: GitHub.