{"record":{"id":"f9064e7b68ed0d10","repo":"chroma-core/chroma","slug":"expected-metadata-value-for-key-key-to-be-a-s","errorCode":null,"errorMessage":"Expected metadata value for key '${key}' to be a string, number, boolean, SparseVector, typed array (string[], number[], boolean[]), or null","messagePattern":"Expected metadata value for key '(.+?)' to be a string, number, boolean, SparseVector, typed array \\(string\\[\\], number\\[\\], boolean\\[\\]\\), or null","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":305,"sourceCode":"\n  for (const [key, v] of Object.entries(metadata)) {\n    if (\n      v === null ||\n      v === undefined ||\n      typeof v === \"string\" ||\n      typeof v === \"number\" ||\n      typeof v === \"boolean\"\n    ) {\n      continue;\n    }\n    if (validateSparseVector(v)) {\n      continue;\n    }\n    if (Array.isArray(v)) {\n      validateMetadataListValue(key, v);\n      continue;\n    }\n    throw new ChromaValueError(\n      `Expected metadata value for key '${key}' to be a string, number, boolean, SparseVector, typed array (string[], number[], boolean[]), or null`,\n    );\n  }\n};\n\nconst SPARSE_VECTOR_TYPE = \"sparse_vector\" as const;\n\ntype SerializedSparseVector = SparseVector & {\n  \"#type\": typeof SPARSE_VECTOR_TYPE;\n};\n\ntype SerializedMetadataValue =\n  | boolean\n  | number\n  | string\n  | SerializedSparseVector\n  | SparseVector\n  | Array<boolean>","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L287-L323","documentation":"The per-key loop in validateMetadata accepts only null/undefined, string, number, boolean, a SparseVector (detected by validateSparseVector), or an array (which is then list-validated). Any other value — plain objects, Dates, Maps, functions — throws ChromaValueError. This mirrors Chroma's metadata model: scalar primitives plus sparse vectors, nothing nested.","triggerScenarios":"metadatas: [{ source: { url: 'x' } }] (nested object). { createdAt: new Date() } (typeof 'object', not an array). A function or Map instance as a value.","commonSituations":"Trying to store structured JSON or timestamps directly in metadata; migrating from another vector DB that allowed object metadata; not realizing only string/number/boolean (plus sparse vectors) are supported.","solutions":["Flatten nested objects into dot- or underscore-separated keys, e.g. { 'source.url': 'x' }.","Serialize Dates with toISOString() and objects with JSON.stringify() before the call.","Keep rich structure in the document text and store only scalar primitives in metadata."],"exampleFix":"// before\nmetadatas: [{ createdAt: new Date(), source: { lang: 'en' } }]\n\n// after\nmetadatas: [{ createdAt: new Date().toISOString(), 'source.lang': 'en' }]","handlingStrategy":"type-guard","validationCode":"const isMetadataValue = (v) =>\n  v == null || ['string', 'number', 'boolean'].includes(typeof v) || Array.isArray(v);\nconst bad = Object.entries(meta).filter(([, v]) => !isMetadataValue(v));\nif (bad.length) throw new Error(`Unsupported metadata keys: ${bad.map(([k]) => k)}`);","typeGuard":"type MetadataValue = string | number | boolean | null | string[] | number[] | boolean[];\nconst isMetadataValue = (v: unknown): v is MetadataValue =>\n  v == null ||\n  ['string', 'number', 'boolean'].includes(typeof v) ||\n  Array.isArray(v);","tryCatchPattern":"try {\n  await collection.add({ ids, metadatas });\n} catch (e) {\n  if ((e as Error).message.includes('SparseVector, typed array')) {\n    // flatten/serialize the offending values and retry\n  } else {\n    throw e;\n  }\n}","preventionTips":["Flatten nested objects to dotted keys at ingestion time.","Always call toISOString() on Dates before storing them in metadata.","Keep a single metadata-builder function that only emits scalars and scalar lists."],"tags":["metadata","type-error","validation","javascript"],"backgroundTag":"invalid-metadata","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}