{"record":{"id":"38c7802def54d70f","repo":"chroma-core/chroma","slug":"the-httpx-python-package-is-not-installed-please-38c780","errorCode":null,"errorMessage":"The httpx python package is not installed. Please install it with `pip install httpx`","messagePattern":"The httpx python package is not installed\\. Please install it with `pip install httpx`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py","lineNumber":44,"sourceCode":"        account_id: str,\n        api_key: Optional[str] = None,\n        api_key_env_var: str = \"CHROMA_CLOUDFLARE_API_KEY\",\n        gateway_id: Optional[str] = None,\n    ):\n        \"\"\"\n        Initialize the CloudflareWorkersAIEmbeddingFunction. See the docs for supported models here:\n        https://developers.cloudflare.com/workers-ai/models/\n\n        Args:\n            model_name: The name of the model to use for text embeddings.\n            account_id: The account ID for the Cloudflare Workers AI API.\n            api_key: The API key for the Cloudflare Workers AI API.\n            api_key_env_var: The environment variable name for the Cloudflare Workers AI API key.\n        \"\"\"\n        try:\n            import httpx\n        except ImportError:\n            raise ValueError(\n                \"The httpx python package is not installed. Please install it with `pip install httpx`\"\n            )\n\n        if api_key is not None:\n            warnings.warn(\n                \"Direct api_key configuration will not be persisted. \"\n                \"Please use environment variables via api_key_env_var for persistent storage.\",\n                DeprecationWarning,\n            )\n        self.model_name = model_name\n        self.account_id = account_id\n\n        if os.getenv(\"CLOUDFLARE_API_KEY\") is not None:\n            self.api_key_env_var = \"CLOUDFLARE_API_KEY\"\n        else:\n            self.api_key_env_var = api_key_env_var\n\n        self.api_key = api_key or os.getenv(self.api_key_env_var)","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\n# import httpx -> ModuleNotFoundError\nef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')  # ValueError: httpx not installed\n\n# after\n# pip install httpx\npython -c 'import httpx; print(httpx.__version__)'\nef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('httpx') is None:\n    raise SystemExit('pip install httpx before using CloudflareWorkersAIEmbeddingFunction')","typeGuard":null,"tryCatchPattern":"try:\n    ef = CloudflareWorkersAIEmbeddingFunction(model_name=M, account_id=A)\nexcept ValueError as e:\n    if 'httpx' in str(e):\n        raise SystemExit(f'Dependency missing: {e}') from e\n    raise","preventionTips":["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."],"tags":["chroma","cloudflare","httpx","missing-dependency","embedding-function"],"backgroundTag":"missing-python-package","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}