{"record":{"id":"3eaa87616e86392c","repo":"chroma-core/chroma","slug":"expected-metadata-list-value-for-key-key-to-b","errorCode":null,"errorMessage":"Expected metadata list value for key '${key}' to be non-empty","messagePattern":"Expected metadata list value for key '(.+?)' to be non-empty","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":265,"sourceCode":"};\n\n/**\n * Validates metadata object for correct types and non-emptiness.\n * @param metadata - Metadata object to validate\n * @throws ChromaValueError if metadata is invalid\n */\nexport const validateMetadata = (metadata?: Metadata) => {\n  if (!metadata) {\n    return;\n  }\n\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        );","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L247-L283","documentation":"The inner list validator in validateMetadata (validateMetadataListValue) throws when a metadata key holds an empty array. Array-valued metadata (string[], number[], boolean[]) must contain at least one element; an empty list is rejected client-side with ChromaValueError before the request is sent. Use null or omit the key to express 'no value'.","triggerScenarios":"collection.add() with metadatas: [{ tags: [] }]. Tag/category lists collected per record where a record has none, e.g. { categories: filteredList } with filteredList empty after filtering.","commonSituations":"Tag arrays derived from user selection or filtering; optional list fields in an ingestion pipeline; defaulting missing lists to [] instead of null.","solutions":["Remove the key or set it to null when the list is empty.","Guard at build time: keep the key only when list.length > 0.","Run a per-key array check before calling add()/upsert()."],"exampleFix":"// before\nconst meta = { tags }; // tags === []\n\n// after\nconst meta = tags.length ? { tags } : null;","handlingStrategy":"validation","validationCode":"const dropEmptyLists = (m) => {\n  if (!m) return null;\n  const out = {};\n  for (const [k, v] of Object.entries(m)) {\n    if (!Array.isArray(v) || v.length > 0) out[k] = v;\n  }\n  return Object.keys(out).length ? out : null;\n};\nconst safe = metadatas.map(dropEmptyLists);","typeGuard":"const isNonEmptyList = (v: unknown): v is [unknown, ...unknown[]] =>\n  Array.isArray(v) && v.length > 0;","tryCatchPattern":"try {\n  await collection.add({ ids, metadatas });\n} catch (e) {\n  if ((e as Error).message.includes('list value for key') && (e as Error).message.includes('non-empty')) {\n    // strip empty list keys, then retry once with cleaned metadata\n  } else {\n    throw e;\n  }\n}","preventionTips":["Treat empty lists like empty metadata: drop the key or use null.","Build list-valued metadata only when list.length > 0.","Log dropped keys during ingestion so silent data loss is visible."],"tags":["metadata","arrays","validation","javascript"],"backgroundTag":"invalid-metadata","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}