{"record":{"id":"635304c751ae963c","repo":"chroma-core/chroma","slug":"cloudflare-api-key-is-required-please-provide-it","errorCode":null,"errorMessage":"Cloudflare API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.","messagePattern":"Cloudflare API key is required\\. Please provide it in the constructor or set the environment variable (.+?)\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/CloudflareWorkersAIEmbeddingFunction.ts","lineNumber":41,"sourceCode":"  private api_url: string;\n  private headers: { [key: string]: string };\n\n  constructor({\n    cloudflare_api_key,\n    model_name,\n    account_id,\n    api_key_env_var = \"CHROMA_CLOUDFLARE_API_KEY\",\n    gateway_id = undefined,\n  }: {\n    cloudflare_api_key?: string;\n    model_name: string;\n    account_id: string;\n    api_key_env_var: string;\n    gateway_id?: string;\n  }) {\n    const apiKey = cloudflare_api_key ?? process.env[api_key_env_var];\n    if (!apiKey) {\n      throw new Error(\n        `Cloudflare API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.`,\n      );\n    }\n\n    this.model_name = model_name;\n    this.account_id = account_id;\n    this.api_key_env_var = api_key_env_var;\n    this.gateway_id = gateway_id;\n\n    if (this.gateway_id) {\n      this.api_url = `${GATEWAY_BASE_URL}/${this.account_id}/${this.gateway_id}/workers-ai/${this.model_name}`;\n    } else {\n      this.api_url = `${BASE_URL}/${this.account_id}/ai/run/${this.model_name}`;\n    }\n\n    this.headers = {\n      Authorization: `Bearer ${apiKey}`,\n      \"Accept-Encoding\": \"identity\",","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/CloudflareWorkersAIEmbeddingFunction.ts#L23-L59","documentation":"CloudflareWorkersAIEmbeddingFunction resolves its API key as cloudflare_api_key ?? process.env[api_key_env_var] (default var name CHROMA_CLOUDFLARE_API_KEY) in the constructor and throws this Error when both are absent. The key is needed for the Workers AI REST call; only the env-var NAME is stored in the persisted config, so on restore (buildFromConfig) the key must again be present in the environment.","triggerScenarios":"new CloudflareWorkersAIEmbeddingFunction({ model_name: '@cf/baai/bge-small-en-v1.5', account_id }) with CHROMA_CLOUDFLARE_API_KEY unset; custom api_key_env_var whose variable was never injected; buildFromConfig on a server where the env var is missing.","commonSituations":"Works locally (exported in shell) but throws on deploy (Vercel/Lambda/K8s missing the secret); .env loaded after the embedding function is constructed; rotating the env var name without updating the deployment.","solutions":["Export the env var: export CHROMA_CLOUDFLARE_API_KEY='<api-key>' (or your custom api_key_env_var).","Or pass the key directly: cloudflare_api_key: process.env.CF_KEY in the constructor options.","For serverless, add the variable to the platform's environment/secret configuration and verify with a startup log of Boolean(process.env[...])."],"exampleFix":"// before\nconst ef = new CloudflareWorkersAIEmbeddingFunction({\n  model_name: '@cf/baai/bge-small-en-v1.5',\n  account_id: 'abc123',\n});\n\n// after\nconst ef = new CloudflareWorkersAIEmbeddingFunction({\n  model_name: '@cf/baai/bge-small-en-v1.5',\n  account_id: 'abc123',\n  cloudflare_api_key: process.env.CLOUDFLARE_API_KEY,\n});","handlingStrategy":"validation","validationCode":"const apiKey = process.env.CHROMA_CLOUDFLARE_API_KEY;\nif (!apiKey) {\n  throw new Error('Set CHROMA_CLOUDFLARE_API_KEY (or pass cloudflare_api_key) before using CloudflareWorkersAIEmbeddingFunction');\n}\nconst ef = new CloudflareWorkersAIEmbeddingFunction({ model_name, account_id, cloudflare_api_key: apiKey });","typeGuard":null,"tryCatchPattern":"try {\n  new CloudflareWorkersAIEmbeddingFunction({ model_name, account_id });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Cloudflare API key is required')) {\n    // inject the secret into the environment and construct again\n  }\n  throw e;\n}","preventionTips":["Check key presence at startup, not lazily at first embed.","On serverless platforms, register the secret in the environment config for every stage.","Remember buildFromConfig relies on the env var, so document it as a deployment prerequisite."],"tags":["embeddings","cloudflare","api-key","environment-variable","credentials"],"backgroundTag":"missing-api-key","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}