{"record":{"id":"cb2731f04e3e9fe2","repo":"headroomlabs-ai/headroom","slug":"error-proxy-dependencies-not-installed-run-pip","errorCode":null,"errorMessage":"Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]","messagePattern":"Error: Proxy dependencies not installed\\. Run: pip install headroom-ai\\[proxy\\]","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/proxy.py","lineNumber":51,"sourceCode":"        \"websockets\",\n        \"onnxruntime\",\n        \"transformers\",\n        \"watchdog\",\n    ]\n    if sys.implementation.name != \"pypy\":\n        required_modules.append(\"orjson\")\n\n    try:\n        for module in required_modules:\n            import_module(module)\n    except ImportError as e:\n        click.secho(\n            \"Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]\",\n            fg=\"red\",\n            err=True,\n        )\n        click.secho(f\"Details: {e}\", fg=\"red\", err=True)\n        raise SystemExit(1) from None\n\n\n# ---------------------------------------------------------------------------\n# Startup log suppression.\n#\n# sentence_transformers makes HEAD/GET requests to HuggingFace Hub on every\n# worker startup to validate the model manifest.  Each request produces an\n# INFO-level httpx record and a WARNING from huggingface_hub about a missing\n# HF_TOKEN.  With 8 workers this generates ~50 noisy lines per startup.\n#\n# Placing the suppression here (module-level in the first CLI module imported)\n# ensures it is in place before sentence_transformers, huggingface_hub, or\n# httpx are initialised by any downstream import or worker fork.\n#\n# The env vars silence the warnings.warn() path (\"unauthenticated requests\"\n# message) which bypasses the logging system entirely.\n# ---------------------------------------------------------------------------\n","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/proxy.py#L33-L69","documentation":"`headroom proxy` builds a list of required modules (uvicorn/fastapi + orjson etc. depending on options) and imports each before starting. Any ImportError triggers the red 'Proxy dependencies not installed. Run: pip install headroom-ai[proxy]' message (with the failing module in Details:) and exit 1. The proxy is an optional heavyweight component, so its deps are not in the base install.","triggerScenarios":"Running `headroom proxy ...` where uvicorn, fastapi, orjson, or another listed module is missing — e.g. bare install, or enabling an option that appends 'orjson' to required_modules without it installed.","commonSituations":"pip install headroom-ai without [proxy]; Docker images slimmed aggressively; option flags (e.g. fast-json paths) that require orjson but environment only has stdlib json.","solutions":["pip install 'headroom-ai[proxy]'","Match the Details: module — if orjson is named and you triggered the fast-json option, either install orjson or drop the flag","For deployments, bake the extra into the image: pip install 'headroom-ai[proxy,mcp]' as needed","Verify all required modules in one shot: python -c \"import uvicorn, fastapi, orjson\""],"exampleFix":"# before\n$ headroom proxy start\n# Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]\n\n# after\n$ pip install 'headroom-ai[proxy]'\n$ headroom proxy start","handlingStrategy":"validation","validationCode":"required = [\"uvicorn\", \"fastapi\"] + ([\"orjson\"] if fast_json else [])\nmissing = [m for m in required if importlib.util.find_spec(m) is None]\nif missing:\n    raise SystemExit(f\"missing proxy deps {missing} — pip install 'headroom-ai[proxy]'\")","typeGuard":null,"tryCatchPattern":"try:\n    import_module(\"uvicorn\")\nexcept ImportError as e:\n    raise SystemExit(f\"proxy extra missing: {e}\") from None","preventionTips":["Install 'headroom-ai[proxy]' wherever the proxy runs, including containers","If you toggle fast-json options, ensure orjson is present or don't enable them","Prefer find_spec() checks over bare imports in multi-worker setups to avoid partial initialization"],"tags":["cli","proxy","optional-dependencies","importerror"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}