{"record":{"id":"fa7975b979894e7c","repo":"chroma-core/chroma","slug":"failed-to-generate-embeddings-response-statuste","errorCode":null,"errorMessage":"Failed to generate embeddings: ${response.statusText}","messagePattern":"Failed to generate embeddings: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/HuggingFaceEmbeddingServerFunction.ts","lineNumber":49,"sourceCode":"      apiKey = api_key;\n    }\n    this.url = url;\n    if (apiKey) {\n      this.headers = {\n        Authorization: `Bearer ${apiKey}`,\n      };\n    }\n  }\n\n  public async generate(texts: string[]) {\n    const response = await fetch(this.url, {\n      method: \"POST\",\n      headers: this.headers,\n      body: JSON.stringify({ inputs: texts }),\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to generate embeddings: ${response.statusText}`);\n    }\n\n    const data = await response.json();\n    return data;\n  }\n\n  buildFromConfig(config: StoredConfig): HuggingFaceEmbeddingServerFunction {\n    return new HuggingFaceEmbeddingServerFunction({\n      url: config.url,\n      api_key_env_var: config.api_key_env_var,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      url: this.url,\n      api_key_env_var: this.api_key_env_var,\n    };","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/HuggingFaceEmbeddingServerFunction.ts#L31-L67","documentation":"HuggingFaceEmbeddingServerFunction.generate() POSTs { inputs: texts } to the configured url (a HuggingFace inference / TEI endpoint) with the headers built at construction. If the response status is not 2xx it throws carrying only response.statusText (e.g. \"Unauthorized\", \"Not Found\") — the response body, which usually contains the actual reason, is discarded, so you must reproduce the request to diagnose the root cause.","triggerScenarios":"Wrong endpoint URL or missing route (404); Authorization header missing/invalid because the env var named by api_key_env_var is unset or empty (401); server overloaded or behind a proxy returning 502/503; request body exceeding the server limit (413).","commonSituations":"Pointing at the HuggingFace model page URL instead of the inference endpoint URL; HF token set in the local shell but not in the container; TEI container not running when the client starts; corporate gateways stripping Authorization headers.","solutions":["Reproduce the exact call to see status and body: curl -X POST \"$URL\" -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' -d '{\"inputs\":[\"ping\"]}'","Confirm the env var named by api_key_env_var is exported in the process making the call (node -e \"console.log(!!process.env.HF_TOKEN)\")","Verify the URL scheme/host/route against the HuggingFace or TEI endpoint documentation","For 5xx/503 responses, confirm the server is up (logs/health endpoint) before retrying with backoff"],"exampleFix":"// before (library code): only statusText is visible\nthrow new Error(`Failed to generate embeddings: ${response.statusText}`);\n\n// after (library-level): keep status and body\nconst body = await response.text();\nthrow new Error(`Failed to generate embeddings: ${response.status} ${response.statusText} ${body.slice(0, 200)}`);","handlingStrategy":"try-catch","validationCode":"async function pingEmbedServer(url: string, headers: Record<string, string>): Promise<void> {\n  const res = await fetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ inputs: [\"ping\"] }),\n    signal: AbortSignal.timeout(5_000),\n  });\n  if (!res.ok) throw new Error(`embedding server unhealthy: ${res.status} ${res.statusText}`);\n}\n// run during startup probes, before relying on generate()","typeGuard":null,"tryCatchPattern":"try {\n  embeddings = await ef.generate(texts);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"Failed to generate embeddings\")) {\n    // statusText-only failure: log it, check auth env var and URL; retry only on transient 5xx, never blind-retry 4xx\n  }\n  throw e;\n}","preventionTips":["Health-check the embedding server as part of startup/readiness probes","Keep the endpoint URL and token env var name in one config module with validation","Cap batch sizes within the server's body limit to avoid 413s"],"tags":["network","http","huggingface","embeddings","server","status-code"],"backgroundTag":"http-request-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}