{"record":{"id":"88b494b2e0d9c500","repo":"Mintplex-Labs/anything-llm","slug":"chromacloud-invalid-heartbeat-received-is-the-i","errorCode":null,"errorMessage":"ChromaCloud::Invalid Heartbeat received - is the instance online?","messagePattern":"ChromaCloud::Invalid Heartbeat received - is the instance online\\?","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/utils/vectorDbProviders/chromacloud/index.js","lineNumber":41,"sourceCode":"    maxEmbeddingDim: 4_096,\n    maxDocumentBytes: 16_384,\n    maxMetadataBytes: 4_096,\n    maxRecordsPerWrite: 300,\n  };\n\n  async connect() {\n    if (process.env.VECTOR_DB !== \"chromacloud\")\n      throw new Error(\"ChromaCloud::Invalid ENV settings\");\n\n    const client = new CloudClient({\n      apiKey: process.env.CHROMACLOUD_API_KEY,\n      tenant: process.env.CHROMACLOUD_TENANT,\n      database: process.env.CHROMACLOUD_DATABASE,\n    });\n\n    const isAlive = await client.heartbeat();\n    if (!isAlive)\n      throw new Error(\n        \"ChromaCloud::Invalid Heartbeat received - is the instance online?\"\n      );\n    return { client };\n  }\n\n  /**\n   * Chroma Cloud has some basic limitations on upserts to protect performance and latency.\n   * Local deployments do not have these limitations since they are self-hosted.\n   *\n   * This method, if cloud, will do some simple logic/heuristics to ensure that the upserts are not too large.\n   * Otherwise, it may throw a 422.\n   * @param {import(\"chromadb\").Collection} collection\n   * @param {{ids: string[], embeddings: number[], metadatas: Record<string, any>[], documents: string[]}[]} submissions\n   * @returns {Promise<boolean>} True if the upsert was successful, false otherwise.\n   * If the upsert was not successful, the error message will be returned.\n   */\n  async smartAdd(collection, submission) {\n    const testSubmission = {","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/3aec848f2885144aa8f1e53b9731a04310d5d558/server/utils/vectorDbProviders/chromacloud/index.js#L23-L59","documentation":"ChromaCloudVectorDb.connect() builds a CloudClient with apiKey/tenant/database from env and calls heartbeat(); a falsy response throws. For the hosted Chroma Cloud this usually means authentication or routing failed (invalid key, wrong tenant/database) or the cloud API is unreachable - not a local server you can restart.","triggerScenarios":"Any Chroma Cloud vector operation when CHROMACLOUD_API_KEY is invalid/expired, CHROMACLOUD_TENANT or CHROMACLOUD_DATABASE names are wrong, or outbound HTTPS to Chroma Cloud is blocked; also transient cloud-side incidents.","commonSituations":"Key rotated in the Chroma Cloud console but .env not updated; tenant/database typo; corporate egress firewall; copy-paste leaving whitespace in the key.","solutions":["Verify the trio CHROMACLOUD_API_KEY / _TENANT / _DATABASE against the Chroma Cloud console, then restart the server.","Test auth directly with the SDK or a curl to the Chroma Cloud API using the same key to isolate AnythingLLM from the credential.","Check cloud status/egress if credentials are confirmed good; retry after transient incidents.","Ensure no quotes/whitespace were introduced when editing .env."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"async function chromaCloudHealthy() {\n  try {\n    const { CloudClient } = await import('chromadb-cloud');\n    const c = new CloudClient({\n      apiKey: process.env.CHROMACLOUD_API_KEY,\n      tenant: process.env.CHROMACLOUD_TENANT,\n      database: process.env.CHROMACLOUD_DATABASE,\n    });\n    return !!(await c.heartbeat());\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await vectorDb.connect();\n} catch (e) {\n  if (/Invalid Heartbeat/i.test(e.message)) {\n    await sleep(5000); // transient cloud incident or cold route\n    return vectorDb.connect();\n  }\n  throw e;\n}","preventionTips":["Store Chroma Cloud credentials in a secret manager and rotate with an env-update + restart runbook.","Verify key/tenant/database in the console after any rotation before restarting the app.","Run a boot-time cloud heartbeat check and fail startup loudly instead of per-request errors."],"tags":["chroma-cloud","vector-db","heartbeat","authentication","network"],"backgroundTag":"service-unavailable","analyzedSha":"3aec848f2885144aa8f1e53b9731a04310d5d558","analyzedAt":"2026-08-18T10:02:21.017Z","contentChangedAt":"2026-08-18T10:02:21.017Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}