{"record":{"id":"037b5b2d4efd0239","repo":"mastra-ai/mastra","slug":"metadata-array-length-must-match-vectors-array-len","errorCode":null,"errorMessage":"Metadata array length must match vectors array length","messagePattern":"Metadata array length must match vectors array length","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/vector/validation.ts","lineNumber":40,"sourceCode":"  vectors: number[][] | undefined | null,\n  metadata?: Record<string, any>[] | null,\n  ids?: string[] | null,\n): void {\n  // Validate vectors array is not empty\n  if (!vectors || vectors.length === 0) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'EMPTY_VECTORS'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'Vectors array cannot be empty',\n      },\n    });\n  }\n\n  // Validate metadata length matches vectors length (skip if metadata is empty/not provided)\n  if (metadata && metadata.length > 0 && metadata.length !== vectors.length) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'METADATA_LENGTH_MISMATCH'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {\n        message: 'Metadata array length must match vectors array length',\n        vectorsLength: vectors.length,\n        metadataLength: metadata.length,\n      },\n    });\n  }\n\n  // Validate ids length matches vectors length\n  if (ids && ids.length !== vectors.length) {\n    throw new MastraError({\n      id: createVectorErrorId(storeName, 'UPSERT', 'IDS_LENGTH_MISMATCH'),\n      domain: ErrorDomain.MASTRA_VECTOR,\n      category: ErrorCategory.USER,\n      details: {","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/vector/validation.ts#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make metadata.length equal vectors.length before calling upsert","Slice both arrays together: vectors.slice(0, n) and metadata.slice(0, n)","If metadata is intentionally partial, pass only complete entries or omit metadata entirely"],"exampleFix":"// before\nawait store.upsert({ indexName: 'docs', vectors, metadata: metadata.slice(0, vectors.length - 2) });\n// after\nif (metadata.length !== vectors.length) {\n  throw new Error(`metadata (${metadata.length}) != vectors (${vectors.length})`);\n}\nawait store.upsert({ indexName: 'docs', vectors, metadata });","handlingStrategy":"validation","validationCode":"if (metadata && metadata.length !== vectors.length) {\n  throw new Error(`metadata ${metadata.length} != vectors ${vectors.length}`);\n}","typeGuard":"function metadataMatches(vectors: number[][], metadata?: Record<string, any>[]): boolean {\n  return !metadata || metadata.length === vectors.length;\n}","tryCatchPattern":"try {\n  await store.upsert({ indexName, vectors, metadata });\n} catch (e) {\n  if (e instanceof MastraError && e.id.includes('METADATA_LENGTH_MISMATCH')) {\n    console.error('vectors:', e.details.vectorsLength, 'metadata:', e.details.metadataLength);\n  }\n  throw e;\n}","preventionTips":["Always derive metadata from the same loop/map that produces vectors","Slice vectors and metadata together when batching","Write an assertion helper for (vectors, metadata, ids) tuples"],"tags":["validation","vector-store","upsert","metadata"],"backgroundTag":"array-length-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}