{"record":{"id":"8e3a22bfa9b54fc6","repo":"chroma-core/chroma","slug":"expected-fieldname-to-be-an-array-but-got-8e3a22","errorCode":null,"errorMessage":"Expected '${fieldName}' to be an array, but got ${typeof documents}","messagePattern":"Expected '(.+?)' to be an array, but got (.+?)","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/utils.ts","lineNumber":163,"sourceCode":"    if (embedding.length === 0) {\n      throw new ChromaValueError(\n        `Expected each embedding to be a non-empty array of numbers, but got an empty array at index ${i}`,\n      );\n    }\n  });\n};\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};","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/utils.ts#L145-L181","documentation":"ChromaValueError thrown by validateDocuments (utils.ts:166) via validateBaseRecordSet when the documents value is not an Array. fieldName is 'documents' for add/update and 'queryTexts' for query, so the message tells you which call site is at fault.","triggerScenarios":"Passing a bare string: collection.add({ ids, documents: 'hello' }) instead of ['hello']; passing an object or Map produced by a loader; query({ queryTexts: someString }).","commonSituations":"Single-record convenience expectation (many SDKs accept a string); refactors that change a variable from string[] to string; query text taken from req.body.q and passed unwrapped.","solutions":["Wrap scalars in an array: documents: [doc]","Keep the field typed as (string|null|undefined)[] so TS flags misuse","Normalize loader output with Array.isArray checks at the boundary"],"exampleFix":"// before\nawait collection.add({ ids: ['1'], documents: 'hello world' });\n// after\nawait collection.add({ ids: ['1'], documents: ['hello world'] });","handlingStrategy":"type-guard","validationCode":"if (!Array.isArray(documents)) throw new TypeError(`documents must be an array, got ${typeof documents}`);","typeGuard":"const isDocumentList = (v) => Array.isArray(v);","tryCatchPattern":"try { await collection.add({ ids, documents }); } catch (e) { if (e instanceof ChromaValueError && /'documents' to be an array|'queryTexts' to be an array/.test(e.message)) documents = [documents]; else throw e; }","preventionTips":["Wrap single strings in [] at the API boundary","Keep documents typed as (string|null|undefined)[]","Normalize loader outputs with Array.isArray checks"],"tags":["chromadb","validation","documents","type-mismatch"],"backgroundTag":"invalid-documents-format","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}