{"record":{"id":"a959d45a4db9cfeb","repo":"chroma-core/chroma","slug":"failed-to-generate-embeddings-for-your-request","errorCode":null,"errorMessage":"Failed to generate embeddings for your request.","messagePattern":"Failed to generate embeddings for your request\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/utils.ts","lineNumber":127,"sourceCode":"export 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    }\n  }\n\n  if (\n    (embeddingsArray !== undefined && ids.length !== embeddingsArray.length) ||\n    (metadatas !== undefined && ids.length !== metadatas.length) ||\n    (documents !== undefined && ids.length !== documents.length)\n  ) {\n    throw new Error(\n      \"ids, embeddings, metadatas, and documents must all be the same length\",\n    );","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/utils.ts#L109-L145","documentation":"After the both-undefined guard, prepareRecordRequest() computes embeddingsArray as the caller-supplied embeddings or `await embeddingFunction.generate(documents)`. If that call returns a falsy value (undefined/null), this error is thrown for add/upsert requests. It almost always means the embedding function itself returned nothing — typically a custom IEmbeddingFunction whose generate() is missing a return or returns undefined on edge inputs.","triggerScenarios":"collection.add({ ids, documents }) where the collection's embedding function is a custom class whose generate(texts) has no return statement, returns undefined for empty/whitespace strings, or returns null on an error path; a default embedding function misconfigured so generate silently yields undefined.","commonSituations":"First run of a hand-written custom IEmbeddingFunction; an `async generate(...)` that does `if (!texts.length) return;` for empty batches; refactors where the return got dropped; generate() that awaits a helper which itself returns undefined.","solutions":["Call the embedding function directly to see the return value: const out = await fn.generate(['ping']); console.log(out?.length, out?.[0]?.length) — you should get [1] and the vector dimension.","Fix generate() to always return number[][] with exactly one vector per input string, including for edge-case inputs.","Unit-test your IEmbeddingFunction implementation against that contract."],"exampleFix":"// before (custom embedding function with no return)\nclass MyEmbedding {\n  async generate(texts: string[]) {\n    texts.map((t) => embed(t)); // missing return -> undefined\n  }\n}\n\n// after\nclass MyEmbedding {\n  async generate(texts: string[]): Promise<number[][]> {\n    return texts.map((t) => embed(t)); // always one vector per input\n  }\n}","handlingStrategy":"validation","validationCode":"// Contract-check your embedding function before wiring it into a collection\nasync function assertEmbeddingContract(fn: IEmbeddingFunction) {\n  const out = await fn.generate([\"ping\"]);\n  if (!Array.isArray(out) || out.length !== 1 || !Array.isArray(out[0])) {\n    throw new Error(\"IEmbeddingFunction.generate must return number[][] with one vector per input\");\n  }\n}\nawait assertEmbeddingContract(myCustomFn);","typeGuard":"const isEmbeddingMatrix = (v: unknown): v is number[][] =>\n  Array.isArray(v) && v.length > 0 && v.every((row) => Array.isArray(row) && row.every((x) => typeof x === \"number\"));","tryCatchPattern":null,"preventionTips":["Unit-test custom IEmbeddingFunction.generate (including empty-string and empty-array inputs) for shape and count.","Type generate()'s return as Promise<number[][]> so a missing return is a compile error, not a runtime surprise."],"tags":["records","embeddings","custom-embedding-function","validation","return-value"],"backgroundTag":"embedding-generation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}