mastra-ai/mastra · error · MastraError

Metadata array length must match vectors array length

Error message

Metadata array length must match vectors array length

What it means

Thrown by validateUpsertInput when the optional metadata array is provided with a length different from the vectors array. Each vector must map 1:1 to a metadata record, so mismatched lengths are rejected as ambiguous.

Source

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

  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,
        metadataLength: metadata.length,
      },
    });
  }

  // Validate ids length matches vectors length
  if (ids && ids.length !== vectors.length) {
    throw new MastraError({
      id: createVectorErrorId(storeName, 'UPSERT', 'IDS_LENGTH_MISMATCH'),
      domain: ErrorDomain.MASTRA_VECTOR,
      category: ErrorCategory.USER,
      details: {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Make metadata.length equal vectors.length before calling upsert
2. Slice both arrays together: vectors.slice(0, n) and metadata.slice(0, n)
3. If metadata is intentionally partial, pass only complete entries or omit metadata entirely

Example fix

// before
await store.upsert({ indexName: 'docs', vectors, metadata: metadata.slice(0, vectors.length - 2) });
// after
if (metadata.length !== vectors.length) {
  throw new Error(`metadata (${metadata.length}) != vectors (${vectors.length})`);
}
await store.upsert({ indexName: 'docs', vectors, metadata });

if (metadata && metadata.length !== vectors.length) {
  throw new Error(`metadata ${metadata.length} != vectors ${vectors.length}`);
}

function metadataMatches(vectors: number[][], metadata?: Record<string, any>[]): boolean {
  return !metadata || metadata.length === vectors.length;
}

try {
  await store.upsert({ indexName, vectors, metadata });
} catch (e) {
  if (e instanceof MastraError && e.id.includes('METADATA_LENGTH_MISMATCH')) {
    console.error('vectors:', e.details.vectorsLength, 'metadata:', e.details.metadataLength);
  }
  throw e;
}

When it happens

Trigger: Calling upsert with e.g. 10 vectors but 8 metadata records; appending metadata for some but not all vectors; forgetting to add metadata for newly pushed vectors.

Common situations: Incrementally pushing to vectors and metadata arrays where only one got the new item; slicing a batch after embedding but before metadata was sliced too.

Related errors

• Vectors array cannot be empty
• 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
• Rule metadata is too large.

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