{"record":{"id":"86a4a5ee2e50061e","repo":"chroma-core/chroma","slug":"jina-ai-api-key-is-required-please-provide-it-in","errorCode":null,"errorMessage":"Jina AI API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.","messagePattern":"Jina AI 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/JinaEmbeddingFunction.ts","lineNumber":62,"sourceCode":"    late_chunking,\n    truncate,\n    dimensions,\n    embedding_type,\n    normalized,\n  }: {\n    jinaai_api_key?: string;\n    model_name?: string;\n    api_key_env_var: string;\n    task?: string;\n    late_chunking?: boolean;\n    truncate?: boolean;\n    dimensions?: number;\n    embedding_type?: string;\n    normalized?: boolean;\n  }) {\n    const apiKey = jinaai_api_key ?? process.env[api_key_env_var];\n    if (!apiKey) {\n      throw new Error(\n        `Jina AI 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.api_key_env_var = api_key_env_var;\n    this.task = task;\n    this.late_chunking = late_chunking;\n    this.truncate = truncate;\n    this.dimensions = dimensions;\n    this.embedding_type = embedding_type;\n    this.normalized = normalized;\n\n    this.api_url = \"https://api.jina.ai/v1/embeddings\";\n    this.headers = {\n      Authorization: `Bearer ${jinaai_api_key}`,\n      \"Accept-Encoding\": \"identity\",\n      \"Content-Type\": \"application/json\",","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/JinaEmbeddingFunction.ts#L44-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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\" })","Or export the env var with exactly the name you pass as api_key_env_var","Verify inside the running process: node -e \"console.log(!!process.env.JINA_API_KEY)\"","Load env config (dotenv) at the entrypoint, before constructing any embedding function"],"exampleFix":"// before\nconst ef = new JinaEmbeddingFunction({ model_name: \"jina-embeddings-v3\", api_key_env_var: \"JINA_API_KEY\" }); // throws if unset\n\n// after\nimport \"dotenv/config\";\nconst ef = new JinaEmbeddingFunction({\n  jinaai_api_key: process.env.JINA_API_KEY!, // explicit; fail-fast at boot if missing\n  model_name: \"jina-embeddings-v3\",\n  api_key_env_var: \"JINA_API_KEY\",\n});","handlingStrategy":"validation","validationCode":"function requireEnv(name: string): string {\n  const v = process.env[name];\n  if (!v) throw new Error(`Missing required env var ${name}`);\n  return v;\n}\n// before constructing:\nconst jinaai_api_key = requireEnv(\"JINA_API_KEY\"); // must match the api_key_env_var you pass below\nconst ef = new JinaEmbeddingFunction({ jinaai_api_key, model_name: \"jina-embeddings-v3\", api_key_env_var: \"JINA_API_KEY\" });","typeGuard":null,"tryCatchPattern":"try {\n  ef = new JinaEmbeddingFunction({ model_name: \"jina-embeddings-v3\", api_key_env_var: \"JINA_API_KEY\" });\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"API key is required\")) {\n    // configuration error: fail boot with a clear message naming the expected env var\n  }\n  throw e;\n}","preventionTips":["Validate all required env vars at boot with a single schema check (e.g. zod) before constructing clients","Pass the key explicitly in addition to the env var name so misconfiguration fails at startup","Load dotenv before any embedding function is constructed"],"tags":["api-key","env-var","jina","configuration","embeddings"],"backgroundTag":"missing-api-key","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}