chroma-core/chroma · error · ChromaForbiddenError

You do not have permission to access the requested resource.

Error message

You do not have permission to access the requested resource.

What it means

Thrown by chromaFetch (chroma-fetch.ts:78) as a ChromaForbiddenError when the Chroma server returns HTTP 403. Unlike 401, authentication succeeded (or is not the issue) but the authenticated principal is not allowed to perform this operation on this resource — the key lacks the required role, scope, or tenant/database access.

Source

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

    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",
        );
      }
      throw new ChromaUniqueError(
        conflictBody.message || "The resource already exists",

View on GitHub (pinned to aecdd12c8a)

Solutions

Check the key's permissions/scopes (client.getUserIdentity() for cloud keys) and grant the needed role or use a key with write access.
Confirm the request targets the tenant/database the key actually belongs to.
If RBAC is misconfigured server-side, fix the role assignments for the user/token.
Separate read-only and read-write client instances if your app mixes both access levels.

Example fix

// before
const ro = new CloudClient({ apiKey: READ_ONLY_KEY });
await ro.createCollection({ name: "new" }); // 403 Forbidden

// after
const rw = new CloudClient({ apiKey: READ_WRITE_KEY });
await rw.createCollection({ name: "new" });
const reader = new CloudClient({ apiKey: READ_ONLY_KEY }); // use only for queries

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await client.createCollection({ name });
} catch (e) {
  if (e instanceof ChromaForbiddenError) {
    // authenticated but not permitted: switch to a key with write scope or fix RBAC; do not retry
  }
  throw e;
}

Prevention

Use separate read-only and read-write clients and pick the right one per operation.
Verify key scopes with getUserIdentity() during deployment smoke tests.
Document required roles per service so key provisioning matches usage.

When it happens

Trigger: Using a read-only API key to create/delete collections or upsert data; accessing a tenant or database the key is not scoped to; RBAC rules on the server denying the role for the endpoint.

Common situations: Down-scoped Chroma Cloud keys used by an app that also writes; shared servers where the key belongs to another tenant; role changes after the key was issued.

Related errors

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