chroma-core/chroma · error · Error

Jina AI API key is required. Please provide it in the constr

Error message

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

What it means

JinaEmbeddingFunction requires an API key at construction: the explicit jinaai_api_key parameter or the environment variable named by api_key_env_var. If neither yields a truthy string the constructor throws synchronously before any request is made, so this fails during client setup rather than at embed time.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/JinaEmbeddingFunction.ts:62

    late_chunking,
    truncate,
    dimensions,
    embedding_type,
    normalized,
  }: {
    jinaai_api_key?: string;
    model_name?: string;
    api_key_env_var: string;
    task?: string;
    late_chunking?: boolean;
    truncate?: boolean;
    dimensions?: number;
    embedding_type?: string;
    normalized?: boolean;
  }) {
    const apiKey = jinaai_api_key ?? process.env[api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `Jina AI 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.api_key_env_var = api_key_env_var;
    this.task = task;
    this.late_chunking = late_chunking;
    this.truncate = truncate;
    this.dimensions = dimensions;
    this.embedding_type = embedding_type;
    this.normalized = normalized;

    this.api_url = "https://api.jina.ai/v1/embeddings";
    this.headers = {
      Authorization: `Bearer ${jinaai_api_key}`,
      "Accept-Encoding": "identity",
      "Content-Type": "application/json",

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Pass the key explicitly: new JinaEmbeddingFunction({ jinaai_api_key: process.env.JINA_API_KEY!, model_name: "jina-embeddings-v3", api_key_env_var: "JINA_API_KEY" })
  2. Or export the env var with exactly the name you pass as api_key_env_var
  3. Verify inside the running process: node -e "console.log(!!process.env.JINA_API_KEY)"
  4. Load env config (dotenv) at the entrypoint, before constructing any embedding function

Example fix

// before
const ef = new JinaEmbeddingFunction({ model_name: "jina-embeddings-v3", api_key_env_var: "JINA_API_KEY" }); // throws if unset

// after
import "dotenv/config";
const ef = new JinaEmbeddingFunction({
  jinaai_api_key: process.env.JINA_API_KEY!, // explicit; fail-fast at boot if missing
  model_name: "jina-embeddings-v3",
  api_key_env_var: "JINA_API_KEY",
});
Defensive patterns

Strategy: validation

Validate before calling

function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`Missing required env var ${name}`);
  return v;
}
// before constructing:
const jinaai_api_key = requireEnv("JINA_API_KEY"); // must match the api_key_env_var you pass below
const ef = new JinaEmbeddingFunction({ jinaai_api_key, model_name: "jina-embeddings-v3", api_key_env_var: "JINA_API_KEY" });

Try / catch

try {
  ef = new JinaEmbeddingFunction({ model_name: "jina-embeddings-v3", api_key_env_var: "JINA_API_KEY" });
} catch (e) {
  if (e instanceof Error && e.message.includes("API key is required")) {
    // configuration error: fail boot with a clear message naming the expected env var
  }
  throw e;
}

Prevention

When it happens

Trigger: new JinaEmbeddingFunction({ model_name: "jina-embeddings-v3", api_key_env_var: "JINAAI_API_KEY" }) with that variable unset and no jinaai_api_key passed; or any custom api_key_env_var name that is not exported in the runtime environment.

Common situations: dotenv loaded after client construction; CI/containers missing the secret; a custom env var name that drifts from what ops exported; key stored in a vault but never injected into the process.

Related errors

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