PrefectHQ/fastmcp · error · ValueError

Missing required config URL

Error message

Missing required config URL

What it means

OIDCProxy requires the URL of the provider's discovery/config document and raises ValueError at construction if config_url is falsy. Without it the proxy cannot discover the provider's endpoints.

Source

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

                token (JWT), decoupling it from the upstream provider's `expires_in`. By
                default (None) the FastMCP access token mirrors the upstream access token
                lifetime. The FastMCP JWT is a reference token re-validated against upstream
                on every request, so a longer FastMCP lifetime does not extend upstream
                access — a revoked or expired upstream session still fails validation. Set
                this for bridges whose upstream issues short-lived access tokens that some
                MCP clients can't refresh gracefully (e.g. `mcp-remote`).
            token_expiry_threshold_seconds: Number of seconds before actual expiry to consider
                a token as expired (default 0). Prevents race conditions where a token
                passes the expiry check but expires before the next operation completes.
            enable_cimd: Whether to enable CIMD (Client ID Metadata Document) client support.
                When True, clients can use their metadata document URL as client_id instead of
                Dynamic Client Registration. Default is True.
            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(

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass the provider's well-known config URL, e.g. https://idp.example.com/.well-known/openid-configuration
2. If it comes from an env var, ensure the variable is set and loaded before constructing the proxy
3. Check argument order/kwarg names so the value isn't silently dropped

Example fix

// before
proxy = OIDCProxy(config_url=os.getenv("OIDC_CONFIG_URL"), client_id="app")  # env unset
// after
assert os.getenv("OIDC_CONFIG_URL"), "OIDC_CONFIG_URL not set"
proxy = OIDCProxy(config_url=os.environ["OIDC_CONFIG_URL"], client_id="app")

config_url = os.environ.get("OIDC_CONFIG_URL")
assert config_url, "OIDC_CONFIG_URL must be set, e.g. https://idp/.well-known/openid-configuration"

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

When it happens

Trigger: Calling OIDCProxy(...) with config_url=None, "", or omitted — often because an env var holding the URL was unset or the argument was misnamed.

Common situations: Missing OIDC_CONFIG_URL-style environment variable; YAML/env config not wired into the constructor; refactor renamed the parameter and the call site still passes the old kwarg positionally.

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 client id
• Missing required base URL
• 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/96aaeec288d9e41f. Report an issue: GitHub.