openai/openai-python · error · OpenAIError

The Bedrock {canonical_family} hostname does not match the s

Error message

The Bedrock {canonical_family} hostname does not match the selected `{endpoint}` endpoint. Set `endpoint='{canonical_family}'` to use this hostname.

What it means

The hostname family parsed from base_url (e.g. `bedrock-runtime`, `bedrock`, `bedrock-agent-runtime`) differs from the `endpoint` value you selected in bedrock(...). Bedrock's different services have distinct hostnames, and mixing them would send signed requests to the wrong service, so the provider refuses.

Source

Thrown at src/openai/providers/bedrock.py:93


def _validate_bedrock_region(region: str | None) -> None:
    if region is not None and _AWS_REGION.fullmatch(region) is None:
        raise OpenAIError("The Bedrock AWS `region` is invalid. Use a standard AWS region such as `us-east-1`.")


def _validate_canonical_bedrock_endpoint(
    base_url: httpx2.URL, *, endpoint: BedrockEndpoint, region: str | None
) -> None:
    canonical_endpoint = _parse_bedrock_endpoint_hostname(base_url.host)
    if canonical_endpoint is None:
        return

    canonical_family, canonical_region = canonical_endpoint
    if base_url.scheme != "https":
        raise OpenAIError("Canonical Amazon Bedrock endpoints require HTTPS.")
    if canonical_family != endpoint:
        raise OpenAIError(
            f"The Bedrock {canonical_family} hostname does not match the selected `{endpoint}` endpoint. "
            f"Set `endpoint='{canonical_family}'` to use this hostname."
        )
    if region is not None and canonical_region != region:
        raise OpenAIError(
            f"The Bedrock endpoint region `{canonical_region}` does not match the configured AWS region `{region}`."
        )


def _default_bedrock_base_url(endpoint: BedrockEndpoint, region: str) -> httpx2.URL:
    hostname = (
        f"bedrock-runtime.{region}.{_runtime_dns_suffixes(region)[0]}"
        if endpoint == "runtime"
        else f"bedrock-mantle.{region}.api.aws"
    )
    return _normalize_base_url(f"https://{hostname}/openai/v1")

View on GitHub (pinned to 9917c6e28e)

Solutions

Set endpoint to the family shown in the message, e.g. `bedrock(endpoint='bedrock')`.
Or change base_url to the hostname matching your selected endpoint.

Example fix

// before
provider = bedrock(base_url="https://bedrock.us-east-1.amazonaws.com")

// after
provider = bedrock(endpoint="bedrock", base_url="https://bedrock.us-east-1.amazonaws.com")

Defensive patterns

Strategy: validation

Validate before calling

from httpx2 import URL
import re
m = re.match(r"^(bedrock[a-z-]*)\.[a-z0-9-]+\.amazonaws\.com$", URL(base_url).host or "")
if m and m.group(1) != endpoint:
    endpoint = m.group(1)  # align endpoint with hostname

Type guard

def endpoint_matches_host(endpoint: str, base_url: str) -> bool:
    import re
    host = URL(base_url).host or ""
    m = re.match(r"^(bedrock[a-z-]*)\.", host)
    return m is None or m.group(1) == endpoint

Try / catch

try:
    provider = bedrock(endpoint=endpoint, base_url=base_url)
except OpenAIError as e:
    if "does not match" in str(e):
        import re
        fam = re.search(r"Set `endpoint='([a-z-]+)'`", str(e))
        provider = bedrock(endpoint=fam.group(1), base_url=base_url)
    else:
        raise

Prevention

Derive the endpoint parameter from the hostname family when configuring custom base_urls.
Prefer omitting base_url so the provider derives it from endpoint+region.
Document which Bedrock service family each base_url targets.

When it happens

Trigger: Selecting `endpoint="runtime"` (default) but passing base_url `https://bedrock.us-east-1.amazonaws.com` (control-plane FIPS or other family), or endpoint="bedrock" with a bedrock-runtime hostname, etc.

Common situations: Copying a base_url for a different Bedrock service from AWS docs; enabling FIPS or a preview endpoint without updating the endpoint parameter.

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/89155542456f16aa. Report an issue: GitHub.