chroma-core/chroma · error · Error

Together AI API key is required. Please provide it in the co

Error message

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

What it means

TogetherAIEmbeddingFunction requires an API key at construction: the explicit together_ai_api_key parameter or the environment variable named by api_key_env_var, which defaults to CHROMA_TOGETHER_AI_API_KEY. If neither yields a truthy string the constructor throws synchronously before any request is made.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/TogetherAIEmbeddingFunction.ts:29

export class TogetherAIEmbeddingFunction implements IEmbeddingFunction {
  name = "together_ai";

  private model_name: string;
  private api_key_env_var: string;
  private headers: { [key: string]: string };

  constructor({
    together_ai_api_key,
    model_name,
    api_key_env_var = "CHROMA_TOGETHER_AI_API_KEY",
  }: {
    together_ai_api_key?: string;
    model_name: string;
    api_key_env_var: string;
  }) {
    const apiKey = together_ai_api_key ?? process.env[api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `Together 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.headers = {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      accept: "application/json",
    };
  }

  public async generate(texts: string[]): Promise<number[][]> {
    try {
      const payload = {
        model: this.model_name,

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the key explicitly: new TogetherAIEmbeddingFunction({ together_ai_api_key: process.env.TOGETHER_API_KEY!, model_name: "...", api_key_env_var: "TOGETHER_API_KEY" })
Or export CHROMA_TOGETHER_AI_API_KEY=... to match the default name
Or set api_key_env_var to your existing variable name and export it
Verify inside the process: node -e "console.log(!!process.env.CHROMA_TOGETHER_AI_API_KEY)"

Example fix

// before: throws — default env var is CHROMA_TOGETHER_AI_API_KEY
const ef = new TogetherAIEmbeddingFunction({ model_name: "togethercomputer/m2-bert-80M-8k-retrieval" });

// after: be explicit
const ef = new TogetherAIEmbeddingFunction({
  together_ai_api_key: process.env.TOGETHER_API_KEY!,
  api_key_env_var: "TOGETHER_API_KEY",
  model_name: "togethercomputer/m2-bert-80M-8k-retrieval",
});

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 — note the default name is CHROMA_TOGETHER_AI_API_KEY:
const together_ai_api_key = requireEnv("TOGETHER_API_KEY");
const ef = new TogetherAIEmbeddingFunction({ together_ai_api_key, api_key_env_var: "TOGETHER_API_KEY", model_name: "togethercomputer/m2-bert-80M-8k-retrieval" });

Try / catch

try {
  ef = new TogetherAIEmbeddingFunction({ model_name: "togethercomputer/m2-bert-80M-8k-retrieval" });
} catch (e) {
  if (e instanceof Error && e.message.includes("API key is required")) {
    // config error: name CHROMA_TOGETHER_AI_API_KEY (default) in the ops message; do not retry
  }
  throw e;
}

Prevention

Pass together_ai_api_key explicitly rather than relying on the CHROMA_TOGETHER_AI_API_KEY default
Validate env vars once at boot with a schema check before constructing clients
Load dotenv at the entrypoint, before any embedding function is constructed

When it happens

Trigger: new TogetherAIEmbeddingFunction({ model_name: "togethercomputer/m2-bert-80M-8k-retrieval" }) with CHROMA_TOGETHER_AI_API_KEY unset and no together_ai_api_key passed; or a custom api_key_env_var name that is not exported in the runtime environment.

Common situations: Assuming TOGETHER_API_KEY is read automatically (the default is CHROMA_TOGETHER_AI_API_KEY); dotenv loaded after client construction; CI/containers missing the secret.

Related errors

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