{"record":{"id":"26e56238674eb053","repo":"headroomlabs-ai/headroom","slug":"fastapi-required-install-pip-install-fastapi-uvi","errorCode":null,"errorMessage":"FastAPI required. Install: pip install fastapi uvicorn httpx","messagePattern":"FastAPI required\\. Install: pip install fastapi uvicorn httpx","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/proxy/server.py","lineNumber":2465,"sourceCode":"    \"\"\"Normalize project-prefixed WebSocket paths before route matching.\"\"\"\n\n    def __init__(self, app: Any) -> None:\n        self.app = app\n\n    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:\n        if scope[\"type\"] == \"websocket\":\n            prefix_project = strip_project_path_prefix(scope)\n            headers = {\n                name.decode(\"latin-1\"): value.decode(\"latin-1\") for name, value in scope[\"headers\"]\n            }\n            set_current_project(classify_project(headers) or prefix_project)\n        await self.app(scope, receive, send)\n\n\ndef create_app(config: ProxyConfig | None = None) -> FastAPI:\n    \"\"\"Create FastAPI application.\"\"\"\n    if not FASTAPI_AVAILABLE:\n        raise ImportError(\"FastAPI required. Install: pip install fastapi uvicorn httpx\")\n\n    from headroom.proxy.forwarded_headers import load_trusted_dashboard_client_cidrs\n\n    # Parse once at startup so invalid operator configuration fails loudly.\n    trusted_dashboard_client_cidrs = load_trusted_dashboard_client_cidrs()\n\n    from contextlib import asynccontextmanager\n\n    # Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis.\n    # Installed here (not at module import) so importing headroom.proxy.server\n    # in tests or library contexts does not silently attach a RotatingFileHandler\n    # to the user's live proxy.log.\n    _setup_file_logging()\n\n    config = config or ProxyConfig()\n\n    # Defensive re-apply of file-backed settings for embedded/non-CLI callers\n    # that construct the app without going through the `headroom` CLI entrypoint","sourceCodeStart":2447,"sourceCodeEnd":2483,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/server.py#L2447-L2483","documentation":"create_app raises ImportError when the optional FastAPI stack is not installed. The server module imports guardedly so library/tests can import it without FastAPI, but constructing the app requires fastapi, uvicorn, and httpx. The message names the exact pip extras needed.","triggerScenarios":"Calling create_app() in an environment where the fastapi/uvicorn/httpx optional group is missing, e.g. minimal install for SDK-only usage, or calling run_server/create_app in a test venv without server extras.","commonSituations":"Installing headroom-core without the proxy/server extra; stale venvs after adding the dependency group; CI job reusing a cached environment.","solutions":["Install extras: pip install fastapi uvicorn httpx.","Prefer the documented server/proxy extras command from the project README if provided.","In library-only code paths, avoid calling create_app/run_server; import specific modules instead."],"exampleFix":"# before\napp = create_app()  # ImportError\n\n# after\n# pip install fastapi uvicorn httpx\napp = create_app()","handlingStrategy":"try-catch","validationCode":"def fastapi_available() -> bool:\n    try:\n        import fastapi, uvicorn, httpx  # noqa: F401\n        return True\n    except ImportError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    app = create_app(config)\nexcept ImportError as e:\n    if \"FastAPI required\" in str(e):\n        sys.exit(\"Install server extras: pip install fastapi uvicorn httpx\")\n    raise","preventionTips":["Pin server extras in the same requirements set as proxy usage.","Fail fast at process start rather than at first request."],"tags":["dependencies","import","server"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}