BerriAI/litellm · error · ValueError

aws_region_name is required in the WIF credential JSON when

Error message

aws_region_name is required in the WIF credential JSON when using explicit AWS authentication. Add "aws_region_name": "<your-region>" to your credential file.

What it means

Validation failure in credentials_from_explicit_aws: the WIF credential JSON contains aws_* parameters but no aws_region_name, which is required for the GCP STS token exchange. It is checked before get_credentials() to avoid a pointless AWS API call.

Source

Thrown at litellm/llms/vertex_ai/vertex_ai_aws_wif.py:81

            aws_params: Dict of aws_* params extracted from json_obj
            scopes: OAuth scopes for the GCP credentials
        """
        try:
            from google.auth import aws
        except ImportError:
            raise ImportError(GOOGLE_IMPORT_ERROR_MESSAGE)

        from litellm.llms.bedrock.base_aws_llm import BaseAWSLLM
        from litellm.llms.vertex_ai.aws_credentials_supplier import (
            AwsCredentialsSupplier,
        )

        # Validate region first — required for the GCP token exchange.
        # Check before get_credentials() to avoid unnecessary AWS API calls
        # (e.g. STS AssumeRole) on misconfiguration.
        aws_region: Final = aws_params.get("aws_region_name")
        if not aws_region:
            raise ValueError(
                "aws_region_name is required in the WIF credential JSON "
                "when using explicit AWS authentication. Add "
                '"aws_region_name": "<your-region>" to your credential file.'
            )

        # Build a credentials provider that re-resolves AWS creds on each call.
        # This ensures rotated/refreshed STS tokens are picked up during
        # long-running processes when google-auth refreshes the GCP token.
        base_aws: Final = BaseAWSLLM()
        aws_params_copy: Final = dict(aws_params)  # avoid mutating caller's dict

        def _get_aws_credentials():
            return base_aws.get_credentials(**aws_params_copy)

        # Create the custom supplier with a lazy credentials provider
        supplier: Final = AwsCredentialsSupplier(
            credentials_provider=_get_aws_credentials,
            aws_region=aws_region,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add "aws_region_name": "<your-region>" to the WIF credential JSON file used for AWS authentication.
2. Alternatively use ambient AWS credentials (env vars / instance metadata) so the region is resolved automatically.

When it happens

Trigger: Thrown at litellm/llms/vertex_ai/vertex_ai_aws_wif.py:81 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/bae2d65aa01f6712. Report an issue: GitHub.