PrefectHQ/fastmcp · error · ValueError

Missing required base URL

Error message

Missing required base URL

What it means

OIDCProxy requires base_url (the publicly reachable URL of the FastMCP server, used to build OAuth redirect/callback routes) and raises ValueError when it is falsy.

Source

Thrown at fastmcp_slim/fastmcp/server/auth/oidc_proxy.py:363

            identity_assertion: Optional SEP-990 identity assertion (ID-JAG) configuration.
                When provided, the token endpoint accepts the RFC 7523 jwt-bearer grant
                carrying an ID-JAG issued by one of the configured trusted issuers.
        """
        if not config_url:
            raise ValueError("Missing required config URL")

        if not client_id:
            raise ValueError("Missing required client id")

        if not client_secret and not jwt_signing_key:
            raise ValueError(
                "Either client_secret or jwt_signing_key must be provided. "
                "jwt_signing_key is required when client_secret is omitted "
                "(e.g., for PKCE public clients)."
            )

        if not base_url:
            raise ValueError("Missing required base URL")

        # Validate that verifier-specific parameters are not used with custom verifier
        if token_verifier is not None:
            if algorithm is not None:
                raise ValueError(
                    "Cannot specify 'algorithm' when providing a custom token_verifier. "
                    "Configure the algorithm on your token verifier instead."
                )
            if required_scopes is not None:
                raise ValueError(
                    "Cannot specify 'required_scopes' when providing a custom token_verifier. "
                    "Configure required scopes on your token verifier instead."
                )

        if isinstance(config_url, str):
            config_url = AnyHttpUrl(config_url)

        self.oidc_config = self.get_oidc_configuration(

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass the server's public base URL (e.g. https://myserver.example.com/) to OIDCProxy
2. Set and load the deployment's BASE_URL env var before constructing the auth provider
3. Also register the resulting callback URL with your OIDC provider to avoid later redirect mismatches

Example fix

// before
proxy = OIDCProxy(config_url=..., client_id="app", client_secret=..., base_url=os.getenv("BASE_URL"))  # unset
// after
base_url = os.environ["BASE_URL"]
proxy = OIDCProxy(config_url=..., client_id="app", client_secret=..., base_url=base_url)

base_url = os.environ.get("BASE_URL")
if not base_url:
    raise ValueError("BASE_URL (public server URL) is required for OAuth callbacks")

try:
    proxy = OIDCProxy(config_url=..., client_id=..., client_secret=..., base_url=base_url)
except ValueError as e:
    logger.error("OIDCProxy misconfigured: %s", e)
    raise SystemExit(1)

When it happens

Trigger: Constructing OIDCProxy(...) with base_url=None/"" or omitted — commonly when the deployment URL env var is unset or the server constructs auth before base_url is known.

Common situations: Local dev behind tunnels where BASE_URL isn't configured; container deployments missing the public hostname env; ordering issue where the auth provider is built before the server URL is computed.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Missing required config URL
• Missing required client id
• OIDC discovery document for issuer {issuer!r} has no jwks_ur
• Missing required configuration metadata: {attr}
• Invalid URL for configuration metadata: {attr}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/d412f807479c9151. Report an issue: GitHub.