chroma-core/chroma · error · Error

Cloudflare API key is required. Please provide it in the con

Error message

Cloudflare API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.

What it means

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.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/CloudflareWorkersAIEmbeddingFunction.ts:41

  private api_url: string;
  private headers: { [key: string]: string };

  constructor({
    cloudflare_api_key,
    model_name,
    account_id,
    api_key_env_var = "CHROMA_CLOUDFLARE_API_KEY",
    gateway_id = undefined,
  }: {
    cloudflare_api_key?: string;
    model_name: string;
    account_id: string;
    api_key_env_var: string;
    gateway_id?: string;
  }) {
    const apiKey = cloudflare_api_key ?? process.env[api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `Cloudflare API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.`,
      );
    }

    this.model_name = model_name;
    this.account_id = account_id;
    this.api_key_env_var = api_key_env_var;
    this.gateway_id = gateway_id;

    if (this.gateway_id) {
      this.api_url = `${GATEWAY_BASE_URL}/${this.account_id}/${this.gateway_id}/workers-ai/${this.model_name}`;
    } else {
      this.api_url = `${BASE_URL}/${this.account_id}/ai/run/${this.model_name}`;
    }

    this.headers = {
      Authorization: `Bearer ${apiKey}`,
      "Accept-Encoding": "identity",

View on GitHub (pinned to aecdd12c8a)

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[...]).

Example fix

// before
const ef = new CloudflareWorkersAIEmbeddingFunction({
  model_name: '@cf/baai/bge-small-en-v1.5',
  account_id: 'abc123',
});

// after
const ef = new CloudflareWorkersAIEmbeddingFunction({
  model_name: '@cf/baai/bge-small-en-v1.5',
  account_id: 'abc123',
  cloudflare_api_key: process.env.CLOUDFLARE_API_KEY,
});

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = process.env.CHROMA_CLOUDFLARE_API_KEY;
if (!apiKey) {
  throw new Error('Set CHROMA_CLOUDFLARE_API_KEY (or pass cloudflare_api_key) before using CloudflareWorkersAIEmbeddingFunction');
}
const ef = new CloudflareWorkersAIEmbeddingFunction({ model_name, account_id, cloudflare_api_key: apiKey });

Try / catch

try {
  new CloudflareWorkersAIEmbeddingFunction({ model_name, account_id });
} catch (e) {
  if (e instanceof Error && e.message.includes('Cloudflare API key is required')) {
    // inject the secret into the environment and construct again
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/635304c751ae963c. Report an issue: GitHub.