Mintplex-Labs/anything-llm · error · Error

ChromaCloud::Invalid Heartbeat received - is the instance on

Error message

ChromaCloud::Invalid Heartbeat received - is the instance online?

What it means

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.

Source

Thrown at server/utils/vectorDbProviders/chromacloud/index.js:41

    maxEmbeddingDim: 4_096,
    maxDocumentBytes: 16_384,
    maxMetadataBytes: 4_096,
    maxRecordsPerWrite: 300,
  };

  async connect() {
    if (process.env.VECTOR_DB !== "chromacloud")
      throw new Error("ChromaCloud::Invalid ENV settings");

    const client = new CloudClient({
      apiKey: process.env.CHROMACLOUD_API_KEY,
      tenant: process.env.CHROMACLOUD_TENANT,
      database: process.env.CHROMACLOUD_DATABASE,
    });

    const isAlive = await client.heartbeat();
    if (!isAlive)
      throw new Error(
        "ChromaCloud::Invalid Heartbeat received - is the instance online?"
      );
    return { client };
  }

  /**
   * Chroma Cloud has some basic limitations on upserts to protect performance and latency.
   * Local deployments do not have these limitations since they are self-hosted.
   *
   * This method, if cloud, will do some simple logic/heuristics to ensure that the upserts are not too large.
   * Otherwise, it may throw a 422.
   * @param {import("chromadb").Collection} collection
   * @param {{ids: string[], embeddings: number[], metadatas: Record<string, any>[], documents: string[]}[]} submissions
   * @returns {Promise<boolean>} True if the upsert was successful, false otherwise.
   * If the upsert was not successful, the error message will be returned.
   */
  async smartAdd(collection, submission) {
    const testSubmission = {

View on GitHub (pinned to 3aec848f28)

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.

Defensive patterns

Strategy: retry

Validate before calling

async function chromaCloudHealthy() {
  try {
    const { CloudClient } = await import('chromadb-cloud');
    const c = new CloudClient({
      apiKey: process.env.CHROMACLOUD_API_KEY,
      tenant: process.env.CHROMACLOUD_TENANT,
      database: process.env.CHROMACLOUD_DATABASE,
    });
    return !!(await c.heartbeat());
  } catch { return false; }
}

Try / catch

try {
  await vectorDb.connect();
} catch (e) {
  if (/Invalid Heartbeat/i.test(e.message)) {
    await sleep(5000); // transient cloud incident or cold route
    return vectorDb.connect();
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Key rotated in the Chroma Cloud console but .env not updated; tenant/database typo; corporate egress firewall; copy-paste leaving whitespace in the key.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@3aec848f28 (2026-08-18). Data as JSON: /api/errors/88b494b2e0d9c500. Report an issue: GitHub.