chroma-core/chroma · error · ValueError

The httpx python package is not installed. Please install it

Error message

The httpx python package is not installed. Please install it with `pip install httpx`

What it means

CloudflareWorkersAIEmbeddingFunction imports httpx lazily inside __init__ because Chroma keeps third-party HTTP clients optional. If httpx is absent, construction aborts with this ValueError before any credential check or API call happens. It is purely an environment/dependency problem, not an API or configuration problem.

Source

Thrown at chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py:44

        account_id: str,
        api_key: Optional[str] = None,
        api_key_env_var: str = "CHROMA_CLOUDFLARE_API_KEY",
        gateway_id: Optional[str] = None,
    ):
        """
        Initialize the CloudflareWorkersAIEmbeddingFunction. See the docs for supported models here:
        https://developers.cloudflare.com/workers-ai/models/

        Args:
            model_name: The name of the model to use for text embeddings.
            account_id: The account ID for the Cloudflare Workers AI API.
            api_key: The API key for the Cloudflare Workers AI API.
            api_key_env_var: The environment variable name for the Cloudflare Workers AI API key.
        """
        try:
            import httpx
        except ImportError:
            raise ValueError(
                "The httpx python package is not installed. Please install it with `pip install httpx`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )
        self.model_name = model_name
        self.account_id = account_id

        if os.getenv("CLOUDFLARE_API_KEY") is not None:
            self.api_key_env_var = "CLOUDFLARE_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install httpx in the environment that runs Chroma, then re-instantiate the embedding function.
Add httpx to requirements.txt/pyproject.toml next to chromadb so environments stay reproducible.
Verify with python -c 'import httpx' using the same interpreter/venv you run Chroma from.

Example fix

# before
# import httpx -> ModuleNotFoundError
ef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')  # ValueError: httpx not installed

# after
# pip install httpx
python -c 'import httpx; print(httpx.__version__)'
ef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('httpx') is None:
    raise SystemExit('pip install httpx before using CloudflareWorkersAIEmbeddingFunction')

Try / catch

try:
    ef = CloudflareWorkersAIEmbeddingFunction(model_name=M, account_id=A)
except ValueError as e:
    if 'httpx' in str(e):
        raise SystemExit(f'Dependency missing: {e}') from e
    raise

Prevention

Declare httpx in the same dependency manifest as chromadb when adopting the Cloudflare EF.
Run a startup smoke test that imports optional provider deps inside the production image.
Use importlib.util.find_spec guards at boot for every optional embedding provider you use.

When it happens

Trigger: Instantiating CloudflareWorkersAIEmbeddingFunction(model_name=..., account_id=...) in an interpreter where httpx is not installed - fresh venv, minimal Docker image, or a requirements list that pulled chromadb without its HTTP client extras.

Common situations: Adopting the Cloudflare embedding function in a project that never needed an HTTP client before; CI caches built from stale lockfiles; slim production images that prune 'unused' transitive dependencies.

Related errors

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