PrefectHQ/fastmcp · error · ValueError

MultiAuth requires at least a server or one verifier

Error message

MultiAuth requires at least a server or one verifier

What it means

A ValueError raised in MultiAuth.__init__ when constructed with neither a FastMCP server instance nor any token verifiers. MultiAuth composes authentication from a server's provider and/or a list of TokenVerifiers; with both empty there is nothing to authenticate with, so construction is rejected immediately.

Source

Thrown at fastmcp_slim/fastmcp/server/auth/auth.py:698

        """Initialize the multi-auth provider.

        Args:
            server: Optional auth provider (e.g., OAuthProxy) that owns routes
                and OAuth metadata. Also participates in token verification as
                the first verifier tried.
            verifiers: One or more token verifiers to try after the server.
            base_url: Override the base URL. Defaults to the server's base_url.
            resource_base_url: Override the protected resource base URL. Defaults
                to the server's resource_base_url when available.
            required_scopes: Override required scopes. Defaults to the server's.
        """
        if verifiers is None:
            verifiers = []
        elif isinstance(verifiers, TokenVerifier):
            verifiers = [verifiers]

        if server is None and not verifiers:
            raise ValueError("MultiAuth requires at least a server or one verifier")

        effective_base_url = base_url or (server.base_url if server else None)
        effective_resource_base_url = resource_base_url or (
            server.resource_base_url if server else None
        )
        effective_scopes = (
            required_scopes
            if required_scopes is not None
            else (server.required_scopes if server else None)
        )

        super().__init__(
            base_url=effective_base_url,
            resource_base_url=effective_resource_base_url,
            required_scopes=effective_scopes,
        )
        self.server = server
        self.verifiers = list(verifiers)

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass at least one TokenVerifier: MultiAuth(verifiers=[JWTVerifier(...)]).
2. Or pass a FastMCP server whose auth provider should be composed: MultiAuth(server=mcp).
3. Log/assert the verifier list length before constructing MultiAuth to catch empty-config cases.

Example fix

// before
auth = MultiAuth(server=None, verifiers=verifiers or [])
// after
if not verifiers:
    raise ValueError('No verifiers configured for MultiAuth')
auth = MultiAuth(verifiers=verifiers)

verifiers = [v for v in verifiers or [] if v is not None]
if server is None and not verifiers:
    raise ValueError('Configure at least one TokenVerifier or a FastMCP server before MultiAuth')
auth = MultiAuth(server=server, verifiers=verifiers)

try:
    auth = MultiAuth(server=server, verifiers=verifiers)
except ValueError as e:
    logger.error('MultiAuth misconfiguration: %s', e)
    raise SystemExit(1) from e

When it happens

Trigger: MultiAuth() with no arguments; MultiAuth(server=None, verifiers=None); MultiAuth(server=None, verifiers=[]) — all reach the 'if server is None and not verifiers' branch and raise.

Common situations: Programmatic config where the server or verifier list is built conditionally and ends up empty (e.g. env-var-driven setup that skipped verifier creation); assuming a list of None entries counts; copy-pasting a MultiAuth snippet without filling in the verifiers.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• OAuth server rejected the static client credentials. Verify
• ClientGroup requires at least one client
• Protocol mode for server {name!r} must be a string
• Subclasses must implement verify_token
• Invalid token issuer

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