{"record":{"id":"5125c3ad871af7d4","repo":"headroomlabs-ai/headroom","slug":"litellm-is-required-for-litellmbackend-install-wi","errorCode":null,"errorMessage":"litellm is required for LiteLLMBackend. Install with: pip install litellm","messagePattern":"litellm is required for LiteLLMBackend\\. Install with: pip install litellm","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/backends/litellm.py","lineNumber":614,"sourceCode":"    def __init__(\n        self,\n        provider: str = \"bedrock\",\n        region: str | None = None,\n        profile_name: str | None = None,\n        **kwargs: Any,\n    ):\n        \"\"\"Initialize LiteLLM backend.\n\n        Args:\n            provider: LiteLLM provider prefix (bedrock, vertex_ai, openrouter, etc.)\n            region: Cloud region (provider-specific)\n            profile_name: AWS named profile for credential resolution (bedrock only).\n                          When set, boto3 uses this profile (e.g. an SSO profile) instead\n                          of the ambient credentials. Ignored for non-bedrock providers.\n            **kwargs: Additional provider-specific config\n        \"\"\"\n        if not LITELLM_AVAILABLE:\n            raise ImportError(\n                \"litellm is required for LiteLLMBackend. Install with: pip install litellm\"\n            )\n\n        self.provider = provider\n        self.region = region\n        self.profile_name = profile_name\n        self.kwargs = kwargs\n\n        # Get provider config from registry\n        self._config = get_provider_config(provider)\n\n        # For Bedrock, fetch model map dynamically from AWS API\n        if provider == \"bedrock\":\n            # litellm takes the botocore-backed `_auth_with_aws_session_token`\n            # path as soon as temporary credentials (AWS_SESSION_TOKEN) are\n            # present. botocore is an optional dependency (the `bedrock`\n            # extra); when it is absent — as in the slim default Docker image —\n            # the failure only surfaces at request time as a misleading","sourceCodeStart":596,"sourceCodeEnd":632,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/backends/litellm.py#L596-L632","documentation":"LiteLLMBackend.__init__ raises ImportError when the optional litellm package is absent (LITELLM_AVAILABLE falsy). Like the other backend guards, it fails at construction time with the exact pip command, rather than at first request.","triggerScenarios":"Instantiating LiteLLMBackend(provider='bedrock'|'vertex_ai'|'openrouter'|..., ...) without litellm installed in the environment.","commonSituations":"Running the slim default Docker image, which omits provider SDKs; installing headroom-ai without the litellm extra; a dependency resolver dropping litellm after a conflict.","solutions":["pip install litellm (or add the appropriate headroom extra that pulls it in).","Rebuild the Docker image with litellm included if you selected the litellm backend in config.","Verify with python -c \"import litellm\" before wiring the backend into startup."],"exampleFix":"# before\nbackend = LiteLLMBackend(provider=\"openrouter\")  # ImportError\n\n# after\n# pip install litellm\nbackend = LiteLLMBackend(provider=\"openrouter\")","handlingStrategy":"validation","validationCode":"def litellm_available() -> bool:\n    try:\n        import litellm  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nassert litellm_available(), \"LiteLLMBackend requires: pip install litellm\"","typeGuard":null,"tryCatchPattern":"try:\n    backend = LiteLLMBackend(provider=\"openrouter\")\nexcept ImportError as e:\n    raise SystemExit(f\"{e}; rebuild the image with litellm installed\") from e","preventionTips":["Include litellm in the deployment whenever the litellm backend is selected in config.","Fail at process start, not first request: construct backends eagerly during startup.","Keep slim images and optional deps in sync via per-backend extras in requirements."],"tags":["python","import","optional-dependency","litellm","backend"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}