chroma-core/chroma · error · ChromaUnauthorizedError

Unauthorized

Error message

Unauthorized

What it means

Thrown by chromaFetch (chroma-fetch.ts:76) as a ChromaUnauthorizedError when the Chroma server returns HTTP 401. It means no credentials were accepted: the request is missing an Authorization header, the API key/token is invalid, or authentication is enabled server-side while the client sent nothing.

Source

Thrown at clients/new-js/packages/chromadb/src/chroma-fetch.ts:76

  if (response.ok) {
    return response;
  }

  switch (response.status) {
    case 400:
      let status = "Bad Request";
      try {
        const responseBody = await response.json();
        status = responseBody.message || status;
      } catch {}
      throw new ChromaClientError(
        `Bad request to ${
          (input as Request).url || "Chroma"
        } with status: ${status}`,
      );
    case 401:
      throw new ChromaUnauthorizedError(`Unauthorized`);
    case 403:
      throw new ChromaForbiddenError(
        `You do not have permission to access the requested resource.`,
      );
    case 404:
      throw new ChromaNotFoundError(
        `The requested resource could not be found`,
      );
    case 409:
      const conflictBody = await getErrorBody(response);
      if (
        conflictBody.error === "ConditionalWriteConflictError" ||
        conflictBody.message === "conditional write conflict"
      ) {
        throw new ChromaConditionalWriteConflictError(
          conflictBody.message || "conditional write conflict",
        );
      }

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Provide valid credentials to the client: new ChromaClient({ path, auth: { provider: 'token', credentials: KEY } }) or the CloudClient apiKey.
2. If auth should be off, remove CHROMA_SERVER_AUTHN* settings from the server and restart it.
3. Rotate/verify the API key in the Chroma Cloud console if it is expired or revoked.
4. Confirm the auth provider matches what the server expects (token vs basic).

Example fix

// before
const client = new ChromaClient({ path: "https://chroma.example.com" }); // server has auth enabled => 401

// after
const client = new ChromaClient({
  path: "https://chroma.example.com",
  auth: { provider: "token", credentials: process.env.CHROMA_TOKEN },
});

if (process.env.CHROMA_API_KEY) {
  client = new CloudClient({ apiKey: process.env.CHROMA_API_KEY });
} else if (process.env.CHROMA_SERVER_AUTH) {
  throw new Error("Server requires auth: set CHROMA_TOKEN / credentials");
}

try {
  await client.listCollections();
} catch (e) {
  if (e instanceof ChromaUnauthorizedError) {
    // 401: no/invalid credentials — configure auth or rotate the key; do not retry
  }
  throw e;
}

When it happens

Trigger: Calling any endpoint on a Chroma server (or Chroma Cloud) with token/basic-auth enabled without credentials, with a malformed Authorization header, or with a revoked/expired API key.

Common situations: Enabling CHROMA_SERVER_AUTHN on a self-hosted server but forgetting to configure credentials in ChromaClient; expired Chroma Cloud API key; wrong type of credentials (token vs basic auth); typos in the key.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Credentials must be supplied via environment variable (CHROM
• Auth credentials not specified
• Cloudflare API key is required. Please provide it in the con
• Cohere API key is required. Please provide it in the constru
• Your API key does not have access to any DBs for tenant ${th

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