chroma-core/chroma · error · ChromaConnectionError

Unable to connect to the chromadb server. Please try again l

Error message

Unable to connect to the chromadb server. Please try again later.

What it means

_parse_k_aggregate() (operator.py:1369-1371) requires the 'k' of a '$min_k'/'$max_k' aggregation to be a Python int and raises TypeError otherwise. k is the per-group record count kept by the aggregation, used directly as MinK(k=...)/MaxK(k=...) (operator.py:1422-1427). Floats (3.0), numeric strings ("3"), and None all fail isinstance(k, int); the check is strict because a non-int k could not bound group sizes reliably. Note the parser checks keys before k, so reaching this error means keys already validated.

Source

Thrown at clients/js/packages/chromadb-core/src/ChromaFetch.ts:92

            `The requested resource could not be found: ${input}`,
          );
        case 409:
          throw new ChromaUniqueError("The resource already exists");
        case 422:
          if (
            respBody?.message &&
            (respBody?.message.startsWith("Quota exceeded") ||
              respBody?.message.startsWith("Billing limit exceeded"))
          ) {
            throw new ChromaQuotaExceededError(respBody?.message);
          }
          break;
        case 500:
          throw parseServerError(respBody?.error);
        case 502:
        case 503:
        case 504:
          throw new ChromaConnectionError(
            `Unable to connect to the chromadb server. Please try again later.`,
          );
      }

      throw new Error(
        `Failed to fetch ${input} with status ${resp.status}: ${resp.statusText}`,
      );
    }

    if (respBody?.error) {
      throw parseServerError(respBody.error);
    }

    return resp;
  } catch (error) {
    if (isOfflineError(error)) {
      throw new ChromaConnectionError(
        "Failed to connect to chromadb. Make sure your server is running and try again. If you are running from a browser, make sure that your chromadb instance is configured to allow requests from the current origin using the CHROMA_SERVER_CORS_ALLOW_ORIGINS environment variable.",

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Write k as a plain integer literal: {"$min_k": {"keys": ["#score"], "k": 3}}.
2. Coerce untyped input before building the payload: k_int = int(k) (or reject non-integer values) — but never send the raw string/float.
3. For NumPy scalars convert explicitly: int(np.int64(n)).
4. Keep k >= 1 — k must also be positive (checked next at operator.py:1372-1373).

Example fix

// before
aggregate = {"$min_k": {"keys": ["#score"], "k": "3"}}   # TypeError: $min_k k must be an integer, got str

# after
aggregate = {"$min_k": {"keys": ["#score"], "k": 3}}

def agg_k_is_int(payload: dict) -> bool:
    op = next(iter(payload))
    body = payload.get(op, {})
    k = body.get("k")
    return isinstance(k, int) and not isinstance(k, bool)

def is_int_k(v: Any) -> TypeGuard[int]:
    return isinstance(v, int) and not isinstance(v, bool)

try:
    Aggregate.from_dict(agg)
except TypeError as e:
    if "k must be an integer" in str(e):
        op = next(iter(agg))
        try:
            agg[op]["k"] = int(agg[op]["k"])
        except (TypeError, ValueError):
            raise ValueError(f"Unusable k value: {agg[op]['k']!r}") from e
    else:
        raise

When it happens

Trigger: {"k": 3.0} from JSON/YAML where the author wrote a float; {"k": "3"} — quoted number from a config or HTML form; {"k": null} — unfilled template placeholder; {"k": [3]} — over-eager wrapping into a list; values arriving via pydantic/YAML typed as float or str.

Common situations: YAML configs where k: 3.0 or k is parsed as float by a loader; strings from env vars or HTTP query params pasted into payloads; jq-based payload builders leaving numbers quoted; NumPy integer scalars from data pipelines (np.int64 is not a Python int and fails the isinstance check in CPython).

Related errors

• The resource already exists
• Failed to fetch ${input} with status ${resp.status}: ${resp.
• Failed to connect to chromadb. Make sure your server is runn
• Unauthorized
• You do not have permission to access the requested resource.

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