headroomlabs-ai/headroom · error · ImportError

Bedrock with temporary credentials (AWS_SESSION_TOKEN) requi

Error message

Bedrock with temporary credentials (AWS_SESSION_TOKEN) requires botocore, which is not installed. Install the bedrock extra: pip install 'headroom-ai[bedrock]' (or pip install botocore).

What it means

LiteLLMBackend raises ImportError at startup when provider='bedrock', AWS_SESSION_TOKEN is set in the environment, and botocore is not installed. litellm routes through a botocore-backed auth path as soon as temporary credentials are present; without botocore that failure would only appear at request time as a misleading 'authentication_error: No module named botocore' (issue #1551), so the check fails fast with an actionable message.

Source

Thrown at headroom/backends/litellm.py:636

        self.provider = provider
        self.region = region
        self.profile_name = profile_name
        self.kwargs = kwargs

        # Get provider config from registry
        self._config = get_provider_config(provider)

        # For Bedrock, fetch model map dynamically from AWS API
        if provider == "bedrock":
            # litellm takes the botocore-backed `_auth_with_aws_session_token`
            # path as soon as temporary credentials (AWS_SESSION_TOKEN) are
            # present. botocore is an optional dependency (the `bedrock`
            # extra); when it is absent — as in the slim default Docker image —
            # the failure only surfaces at request time as a misleading
            # `authentication_error: No module named 'botocore'` (#1551). Fail
            # fast at startup with an actionable message instead.
            if os.environ.get("AWS_SESSION_TOKEN") and importlib.util.find_spec("botocore") is None:
                raise ImportError(
                    "Bedrock with temporary credentials (AWS_SESSION_TOKEN) requires "
                    "botocore, which is not installed. Install the bedrock extra: "
                    "pip install 'headroom-ai[bedrock]' (or pip install botocore)."
                )
            self._model_map = _fetch_bedrock_inference_profiles(region, profile_name=profile_name)
            litellm.set_verbose = False  # Reduce noise
        else:
            self._model_map = self._config.model_map

        # Operator override map (all providers; only meaningful for Bedrock
        # today). Lets you pin a plain model name to a specific target the
        # AWS discovery can't disambiguate — e.g. a per-user application
        # inference profile ARN for cost attribution. See
        # `_parse_bedrock_model_overrides`.
        self._model_overrides = _parse_bedrock_model_overrides(
            os.environ.get("HEADROOM_BEDROCK_MODEL_MAP")
        )
        if self._model_overrides:

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: pip install 'headroom-ai[bedrock]' (or pip install botocore) and rebuild the image.
2. Alternatively use persistent credentials (long-lived access keys) so the botocore path is not required.
3. If the session token is stale/leftover from another account, unset AWS_SESSION_TOKEN and authenticate properly for the target account.

Example fix

# before (Dockerfile, slim image)
RUN pip install headroom-ai
# at runtime: AWS_SESSION_TOKEN=... -> ImportError

# after
RUN pip install 'headroom-ai[bedrock]'

import importlib.util, os

def bedrock_ready_for_env() -> bool:
    if os.environ.get("HEADROOM_PROVIDER", "") != "bedrock":
        return True
    if not os.environ.get("AWS_SESSION_TOKEN"):
        return True  # long-lived creds: botocore path not required
    return importlib.util.find_spec("botocore") is not None

if not bedrock_ready_for_env():
    raise SystemExit("temp AWS creds need botocore: pip install 'headroom-ai[bedrock]'")

try:
    backend = LiteLLMBackend(provider="bedrock")
except ImportError as e:
    if "botocore" in str(e):
        raise SystemExit("install the bedrock extra in this image") from e
    raise

When it happens

Trigger: provider='bedrock' + AWS_SESSION_TOKEN in env (SSO role, assumed role, ECS/GitHub Actions task role) + slim image without the bedrock extra.

Common situations: Running the slim Docker image inside AWS (ECS/Fargate task roles inject AWS_SESSION_TOKEN), CI with OIDC-assumed roles, or aws sso login --profile wrappers; works locally with long-lived keys, breaks in temp-credential environments.

Related errors

• bedrock_sigv4_failed
• any-llm-sdk is required for AnyLLMBackend. Install with: pip
• litellm is required for LiteLLMBackend. Install with: pip in
• Strands SDK is required for this integration. Install with:
• bedrock_upstream_exception

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/475e35ba29af72e4. Report an issue: GitHub.