PrefectHQ/fastmcp · error · ValueError

Missing required client id

Error message

Missing required client id

What it means

OIDCProxy requires a client_id (the client registered with the OIDC provider) and raises ValueError at construction when it is missing or empty. OAuth flows cannot identify the application to the provider without it.

Source

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

                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(
                    "Cannot specify 'algorithm' when providing a custom token_verifier. "
                    "Configure the algorithm on your token verifier instead."
                )

View on GitHub (pinned to 1f02114297)

Solutions

1. Register an OAuth client with your provider and pass its client_id to OIDCProxy
2. Ensure the env var/secret holding the client id is set in the deployment environment
3. Fail fast at startup with an explicit check before constructing the proxy

Example fix

// before
proxy = OIDCProxy(config_url=..., client_id=os.getenv("CLIENT_ID"))  # None
// after
client_id = os.environ["OIDC_CLIENT_ID"]
proxy = OIDCProxy(config_url=..., client_id=client_id)

client_id = os.environ.get("OIDC_CLIENT_ID")
if not client_id:
    raise ValueError("OIDC_CLIENT_ID env var is required")

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

When it happens

Trigger: Constructing OIDCProxy(...) with client_id=None or "" — typically an unset environment variable or a config object that omitted the field.

Common situations: Deployed without the CLIENT_ID secret configured; secrets manager key renamed; local .env not loaded in the runtime environment.

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 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/2077b848777d02e0. Report an issue: GitHub.