chroma-core/chroma · error · ValueError

Missing required arguments: {', '.join([arg.name for arg in

Error message

Missing required arguments: {', '.join([arg.name for arg in missing_args])}. Please provide them or set the environment variables: {', '.join([arg.env_var for arg in missing_args])}

What it means

CloudClient() requires an API key for Chroma Cloud. It first checks the api_key argument, then falls back to os.environ['CHROMA_API_KEY']; if neither is present it raises ValueError listing the missing argument names and the environment variables to set (chromadb/__init__.py:407-413). CHROMA_TENANT and CHROMA_DATABASE are optional and resolved afterwards, so only a missing api_key triggers this.

Source

Thrown at chromadb/__init__.py:413

    Returns:
        ClientAPI: A configured client instance.

    Raises:
        ValueError: If no API key is provided or available in the environment.
    """

    required_args = [
        CloudClientArg(name="api_key", env_var="CHROMA_API_KEY", value=api_key),
    ]

    # If api_key is not provided, try to load it from the environment variable
    if not all([arg.value for arg in required_args]):
        for arg in required_args:
            arg.value = arg.value or os.environ.get(arg.env_var)

    missing_args = [arg for arg in required_args if arg.value is None]
    if missing_args:
        raise ValueError(
            f"Missing required arguments: {', '.join([arg.name for arg in missing_args])}. "
            f"Please provide them or set the environment variables: {', '.join([arg.env_var for arg in missing_args])}"
        )

    if settings is None:
        settings = Settings()

    # Make sure paramaters are the correct types -- users can pass anything.
    tenant = tenant or os.environ.get("CHROMA_TENANT")
    if tenant is not None:
        tenant = str(tenant)
    database = database or os.environ.get("CHROMA_DATABASE")
    if database is not None:
        database = str(database)
    api_key = str(api_key)
    cloud_host = str(cloud_host)
    cloud_port = int(cloud_port)
    enable_ssl = bool(enable_ssl)

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the key explicitly: CloudClient(api_key=...)
Or export CHROMA_API_KEY in the runtime environment (load .env before constructing the client)
Fail fast at startup by checking presence without printing the value: python -c "import os; print(bool(os.environ.get('CHROMA_API_KEY')))"

Example fix

# before
client = CloudClient()  # ValueError: Missing required arguments: api_key

# after
import os
client = CloudClient(api_key=os.environ['CHROMA_API_KEY'])

Defensive patterns

Strategy: validation

Validate before calling

import os

api_key = os.environ.get('CHROMA_API_KEY')
if not api_key:
    raise RuntimeError(
        'CHROMA_API_KEY is not set; export it or pass api_key= to CloudClient'
    )
client = chromadb.CloudClient(api_key=api_key)

Try / catch

try:
    client = chromadb.CloudClient()
except ValueError as e:
    if 'Missing required arguments' in str(e):
        # prompt for the key / abort deployment with a clear message;
        # do NOT hardcode the key as a fallback
        raise
    raise

Prevention

Fail fast at startup: assert the key's presence before creating the client
Manage CHROMA_API_KEY through the platform's secret store (env injection), never in code
Check presence with bool(os.environ.get('CHROMA_API_KEY')) — never print the value

When it happens

Trigger: CloudClient() with no api_key argument and no CHROMA_API_KEY in the environment; a typo'd variable name such as CHROMA_APIKEY; a .env file that was never loaded in the deployed runtime.

Common situations: Works locally (key exported in the shell) but fails in CI, containers, or serverless where env vars are not propagated; key-rotation scripts that unset the variable before recreating the client.

Related errors

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