{"record":{"id":"12938dbc6f605d51","repo":"chroma-core/chroma","slug":"expected-fieldname-to-be-a-non-empty-list","errorCode":null,"errorMessage":"Expected '${fieldName}' to be a non-empty list","messagePattern":"Expected '(.+?)' to be a non-empty list","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":169,"sourceCode":"};\n\nconst validateDocuments = ({\n  documents,\n  nullable = false,\n  fieldName = \"documents\",\n}: {\n  documents: (string | null | undefined)[];\n  fieldName: string;\n  nullable?: boolean;\n}) => {\n  if (!Array.isArray(documents)) {\n    throw new ChromaValueError(\n      `Expected '${fieldName}' to be an array, but got ${typeof documents}`,\n    );\n  }\n\n  if (documents.length === 0) {\n    throw new ChromaValueError(\n      `Expected '${fieldName}' to be a non-empty list`,\n    );\n  }\n\n  documents.forEach((document) => {\n    if (!nullable && typeof document !== \"string\" && !document) {\n      throw new ChromaValueError(\n        `Expected each document to be a string, but got ${typeof document}`,\n      );\n    }\n  });\n};\n\n/**\n * Validates an array of IDs for type correctness and uniqueness.\n * @param ids - Array of ID strings to validate\n * @throws ChromaValueError if IDs are not strings, empty, or contain duplicates\n */","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L151-L187","documentation":"ChromaValueError thrown by validateDocuments (utils.ts:169) when the documents array is present but empty ([]). A batch with no documents cannot be added, updated, or queried, so the client rejects it before any request.","triggerScenarios":"collection.add({ ids, documents: [] }); query({ queryTexts: [] }); documents arrays emptied by an upstream filter.","commonSituations":"Search endpoints queried with an empty list of terms; ingestion loops hitting an empty page; conditionally building documents from rows where none matched.","solutions":["Skip the call when documents is empty: if (!documents.length) return","Guard at the API boundary (e.g. HTTP handler returns 400 before touching Chroma)","Omit the documents field if you intend to pass embeddings only"],"exampleFix":"// before\nawait collection.query({ queryTexts: [], nResults: 5 });\n// after\nif (queryTexts.length === 0) return { results: [] };\nawait collection.query({ queryTexts, nResults: 5 });","handlingStrategy":"validation","validationCode":"if (Array.isArray(documents) && documents.length === 0) return { results: [] };","typeGuard":"const hasDocuments = (d) => Array.isArray(d) && d.length > 0;","tryCatchPattern":"try { await collection.query({ queryTexts: texts, nResults: 5 }); } catch (e) { if (e instanceof ChromaValueError && /non-empty list/.test(e.message)) return { results: [] }; else throw e; }","preventionTips":["Early-return on empty search terms","Guard empty ingestion pages before calling add","Omit documents when passing embeddings only"],"tags":["chromadb","validation","documents","empty-array"],"backgroundTag":"empty-documents-array","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}