{"record":{"id":"085eb8ce2c38f249","repo":"chroma-core/chroma","slug":"unauthorized-085eb8","errorCode":null,"errorMessage":"Unauthorized","messagePattern":"Unauthorized","errorType":"http","errorClass":"ChromaUnauthorizedError","httpStatus":401,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":76,"sourceCode":"\n  if (response.ok) {\n    return response;\n  }\n\n  switch (response.status) {\n    case 400:\n      let status = \"Bad Request\";\n      try {\n        const responseBody = await response.json();\n        status = responseBody.message || status;\n      } catch {}\n      throw new ChromaClientError(\n        `Bad request to ${\n          (input as Request).url || \"Chroma\"\n        } with status: ${status}`,\n      );\n    case 401:\n      throw new ChromaUnauthorizedError(`Unauthorized`);\n    case 403:\n      throw new ChromaForbiddenError(\n        `You do not have permission to access the requested resource.`,\n      );\n    case 404:\n      throw new ChromaNotFoundError(\n        `The requested resource could not be found`,\n      );\n    case 409:\n      const conflictBody = await getErrorBody(response);\n      if (\n        conflictBody.error === \"ConditionalWriteConflictError\" ||\n        conflictBody.message === \"conditional write conflict\"\n      ) {\n        throw new ChromaConditionalWriteConflictError(\n          conflictBody.message || \"conditional write conflict\",\n        );\n      }","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L58-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide valid credentials to the client: new ChromaClient({ path, auth: { provider: 'token', credentials: KEY } }) or the CloudClient apiKey.","If auth should be off, remove CHROMA_SERVER_AUTHN* settings from the server and restart it.","Rotate/verify the API key in the Chroma Cloud console if it is expired or revoked.","Confirm the auth provider matches what the server expects (token vs basic)."],"exampleFix":"// before\nconst client = new ChromaClient({ path: \"https://chroma.example.com\" }); // server has auth enabled => 401\n\n// after\nconst client = new ChromaClient({\n  path: \"https://chroma.example.com\",\n  auth: { provider: \"token\", credentials: process.env.CHROMA_TOKEN },\n});","handlingStrategy":"try-catch","validationCode":"if (process.env.CHROMA_API_KEY) {\n  client = new CloudClient({ apiKey: process.env.CHROMA_API_KEY });\n} else if (process.env.CHROMA_SERVER_AUTH) {\n  throw new Error(\"Server requires auth: set CHROMA_TOKEN / credentials\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.listCollections();\n} catch (e) {\n  if (e instanceof ChromaUnauthorizedError) {\n    // 401: no/invalid credentials — configure auth or rotate the key; do not retry\n  }\n  throw e;\n}","preventionTips":["Fail fast: call a cheap authenticated endpoint at startup to validate credentials.","Store keys in a secret manager and rotate before expiry.","Match the auth provider (token vs basic) to the server configuration."],"tags":["auth","http-401","api-key","credentials"],"backgroundTag":"authentication-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}