{"record":{"id":"27d8d56c1734f0ce","repo":"chroma-core/chroma","slug":"expected-metadata-list-value-for-key-key-to-c","errorCode":null,"errorMessage":"Expected metadata list value for key '${key}' to contain only strings, numbers, or booleans, got ${typeof item}","messagePattern":"Expected metadata list value for key '(.+?)' to contain only strings, numbers, or booleans, got (.+?)","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":276,"sourceCode":"\n  if (Object.keys(metadata).length === 0) {\n    throw new ChromaValueError(\"Expected metadata to be non-empty\");\n  }\n\n  const validateMetadataListValue = (key: string, v: unknown[]): void => {\n    if (v.length === 0) {\n      throw new ChromaValueError(\n        `Expected metadata list value for key '${key}' to be non-empty`,\n      );\n    }\n    const firstType = typeof v[0];\n    for (const item of v) {\n      if (\n        typeof item !== \"string\" &&\n        typeof item !== \"number\" &&\n        typeof item !== \"boolean\"\n      ) {\n        throw new ChromaValueError(\n          `Expected metadata list value for key '${key}' to contain only strings, numbers, or booleans, got ${typeof item}`,\n        );\n      }\n      if (typeof item !== firstType) {\n        throw new ChromaValueError(\n          `Expected metadata list value for key '${key}' to contain only the same type, got mixed types`,\n        );\n      }\n    }\n  };\n\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\"","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L258-L294","documentation":"validateMetadataListValue rejects arrays whose elements are not all string, number, or boolean. Objects, null, undefined, nested arrays, Dates, or any other type inside a metadata list raise ChromaValueError before the request leaves the client. The valid scalar set mirrors Chroma's metadata model: string, number (int/float), and boolean only.","triggerScenarios":"metadatas: [{ authors: ['Ada', { name: 'Grace' }] }] (object inside list). Lists containing null, e.g. { labels: ['a', null] }. Dates inside a list, e.g. { dates: [new Date()] } (typeof 'object').","commonSituations":"Serializing rich domain objects into metadata without flattening; optional list entries encoded as null; Date or BigInt values not converted to strings/numbers first.","solutions":["Map every element to a primitive before the call (explicit field extraction or String()/Number()).","Filter out null/undefined entries: list.filter(v => v != null).","Serialize Dates with toISOString() and nested objects with JSON.stringify() before putting them in a metadata list."],"exampleFix":"// before\nmetadatas: [{ dates: [new Date('2024-01-01')] }]\n\n// after\nmetadatas: [{ dates: [new Date('2024-01-01').toISOString()] }]","handlingStrategy":"validation","validationCode":"const isScalar = (v) => ['string', 'number', 'boolean'].includes(typeof v);\nconst listsOk = Object.values(meta).every(v => !Array.isArray(v) || (v.length > 0 && v.every(isScalar)));","typeGuard":"const isScalarList = (v: unknown): v is (string | number | boolean)[] =>\n  Array.isArray(v) && v.every(item =>\n    typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean'\n  );","tryCatchPattern":"try {\n  await collection.add({ ids, metadatas });\n} catch (e) {\n  if ((e as Error).message.includes('contain only strings, numbers, or booleans')) {\n    // serialize offending elements (String()/toISOString()) and retry\n  } else {\n    throw e;\n  }\n}","preventionTips":["Convert Dates, BigInts, and nested objects to primitives before building metadata lists.","Filter null/undefined out of list values at ingestion.","Validate list element types in the same place you build them, not at call sites."],"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"}