{"record":{"id":"15a60c03d4d7708b","repo":"chroma-core/chroma","slug":"expected-metadatas-to-be-an-array-but-got-typeo","errorCode":null,"errorMessage":"Expected metadatas to be an array, but got ${typeof metadatas}","messagePattern":"Expected metadatas to be an array, but got (.+?)","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":464,"sourceCode":"  }\n\n  if (metadatas === null) {\n    return null;\n  }\n\n  return metadatas.map((metadataArray) => {\n    if (metadataArray === null) {\n      return null;\n    }\n\n    const deserialized = deserializeMetadatas(metadataArray);\n    return deserialized ?? [];\n  });\n};\n\nconst validateMetadatas = (metadatas: Metadata[]) => {\n  if (!Array.isArray(metadatas)) {\n    throw new ChromaValueError(\n      `Expected metadatas to be an array, but got ${typeof metadatas}`,\n    );\n  }\n\n  metadatas.forEach((metadata) => validateMetadata(metadata));\n};\n\n/**\n * Validates a base record set for required fields and data consistency.\n * @param options - Validation options\n * @param options.recordSet - The record set to validate\n * @param options.update - Whether this is for an update operation (relaxes requirements)\n * @param options.embeddingsField - Name of the embeddings field for error messages\n * @param options.documentsField - Name of the documents field for error messages\n * @throws ChromaValueError if validation fails\n */\nexport const validateBaseRecordSet = ({\n  recordSet,","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L446-L482","documentation":"validateMetadatas, invoked from validateBaseRecordSet during add/upsert, requires the metadatas argument to be an array (one metadata object or null per record, aligned with ids). Passing an object, a string, or any non-array raises ChromaValueError client-side. TypeScript types usually prevent this; untyped JavaScript or deserialized payloads can trigger it.","triggerScenarios":"collection.add({ metadatas: { genre: 'sci-fi' } }) — single object instead of an array. metadatas: JSON.parse(raw) where the payload is an object. metadatas: 'none'.","commonSituations":"Copying a single-record example into a batched call without wrapping in an array; passing deserialized JSON whose shape differs from the typed contract; JS callers bypassing TypeScript checks.","solutions":["Wrap per-record metadata in an array with one entry per id: metadatas: [{ genre: 'sci-fi' }].","Check Array.isArray(metadatas) before calling add()/upsert() when input comes from external data.","Keep metadatas, documents, and ids the same length."],"exampleFix":"// before\nawait collection.add({ ids: ['1'], documents: ['d'], metadatas: { genre: 'sci-fi' } });\n\n// after\nawait collection.add({ ids: ['1'], documents: ['d'], metadatas: [{ genre: 'sci-fi' }] });","handlingStrategy":"validation","validationCode":"if (!Array.isArray(metadatas)) {\n  throw new TypeError('metadatas must be an array with one entry per id');\n}\nawait collection.add({ ids, metadatas });","typeGuard":"const isMetadataArray = (v: unknown): v is unknown[] => Array.isArray(v);","tryCatchPattern":"try {\n  await collection.add({ ids, metadatas });\n} catch (e) {\n  if ((e as Error).message.includes('metadatas to be an array')) {\n    await collection.add({ ids, metadatas: [metadatas] }); // wrap single object\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always pass metadatas as an array aligned with ids/documents in length.","Validate external payloads with Array.isArray before calling add()/upsert().","Enable TypeScript checking (the typed client rejects this at compile time)."],"tags":["metadata","validation","javascript","type-error"],"backgroundTag":"invalid-metadata","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}