{"record":{"id":"0a157ae2247e67c3","repo":"chroma-core/chroma","slug":"embeddings-and-documents-cannot-both-be-undefined","errorCode":null,"errorMessage":"embeddings and documents cannot both be undefined","messagePattern":"embeddings and documents cannot both be undefined","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/utils.ts","lineNumber":117,"sourceCode":"    embeddings: params.embeddings\n      ? toArrayOfArrays(params.embeddings)\n      : undefined,\n    metadatas: params.metadatas\n      ? toArray<Metadata>(params.metadatas)\n      : undefined,\n    documents: params.documents ? toArray(params.documents) : undefined,\n  };\n}\n\nexport async function prepareRecordRequest(\n  reqParams: AddRecordsParams | UpdateRecordsParams,\n  embeddingFunction: IEmbeddingFunction,\n  update?: true,\n): Promise<MultiRecordOperationParams> {\n  const { ids, embeddings, metadatas, documents } = arrayifyParams(reqParams);\n\n  if (!embeddings && !documents && !update) {\n    throw new Error(\"embeddings and documents cannot both be undefined\");\n  }\n\n  const embeddingsArray = embeddings\n    ? embeddings\n    : documents\n    ? await embeddingFunction.generate(documents)\n    : undefined;\n\n  if (!embeddingsArray && !update) {\n    throw new Error(\"Failed to generate embeddings for your request.\");\n  }\n\n  for (let i = 0; i < ids.length; i += 1) {\n    if (typeof ids[i] !== \"string\") {\n      throw new Error(\n        `Expected ids to be strings, found ${typeof ids[i]} at index ${i}`,\n      );\n    }","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/utils.ts#L99-L135","documentation":"prepareRecordRequest() is used by Collection.add() and Collection.upsert() (the update flag is not set for those). If the request provides neither `embeddings` nor `documents`, there is nothing to embed or store as text, so it rejects before any network call. Attaching an embedding function to the collection does not help — the function needs documents as input.","triggerScenarios":"collection.add({ ids: ['1'] }); collection.upsert({ ids, metadatas }) without documents or embeddings; code building params dynamically where params.documents ends up undefined (destructuring, optional chaining, an early return upstream).","commonSituations":"Indexing rows that only have metadata and expecting the server to embed metadata; a bug in record-building code silently producing undefined documents; porting code from another vector DB where ids-only inserts are allowed.","solutions":["Pass documents so the embedding function can generate vectors: collection.add({ ids, documents }).","Or pass precomputed embeddings: collection.add({ ids, embeddings }) — one vector per id.","If the intent was a metadata-only update of existing records, use collection.update({ ids, metadatas }), which permits omitting both."],"exampleFix":"// before\nawait collection.add({ ids: [\"doc1\"], metadatas: [{ src: \"a\" }] }); // no documents/embeddings -> throws\n\n// after\nawait collection.add({\n  ids: [\"doc1\"],\n  documents: [\"the text to embed\"],\n  metadatas: [{ src: \"a\" }],\n});","handlingStrategy":"validation","validationCode":"function assertAddParams(params: { ids: string[]; documents?: string[]; embeddings?: number[][] }) {\n  if (!params.documents && !params.embeddings) {\n    throw new Error(\"collection.add requires documents (to embed) or embeddings; got neither.\");\n  }\n}\nassertAddParams(params);\nawait collection.add(params);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build add() params from a typed record shape ({ id, text }) so documents can never be silently undefined.","Add a unit assertion in ingestion pipelines that documents.length > 0 before calling add()."],"tags":["records","add","upsert","validation","embeddings"],"backgroundTag":"missing-documents-or-embeddings","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}