PrefectHQ/fastmcp · error · AuthorizationError

Authorization failed for prompt '{prompt_name}': insufficien

Error message

Authorization failed for prompt '{prompt_name}': insufficient permissions

What it means

Raised as AuthorizationError when the prompt exists and component auth denied access, but no specific missing scopes could be identified (missing was empty). The middleware cannot say what would fix it, so it reports generic 'insufficient permissions' — the denial came from an auth check that does not express a scope shortfall.

Source

Thrown at fastmcp_slim/fastmcp/server/middleware/authorization.py:450

                f"Authorization failed for prompt '{prompt_name}': "
                "not found or not authorized"
            )

        # Global auth check
        token = get_access_token()
        ctx = AuthContext(token=token, component=prompt)
        authorized, missing = await run_auth_checks_with_shortfall(self.auth, ctx)
        if not authorized:
            if missing:
                missing = self._chain_shortfall(missing, ctx, fastmcp.fastmcp)
                raise InsufficientScopeError(
                    missing,
                    message=(
                        f"Authorization failed for prompt '{prompt_name}': "
                        f"insufficient scope (required: {', '.join(missing)})"
                    ),
                )
            raise AuthorizationError(
                f"Authorization failed for prompt '{prompt_name}': insufficient permissions"
            )

        return await call_next(context)

View on GitHub (pinned to 1f02114297)

Solutions

Inspect any custom auth predicates/functions attached to the prompt and confirm why the caller's token (claims, roles, subject) fails them.
Verify the AuthProvider's allow/deny rules for this component — a role-based or claim-based denial will surface this way rather than as missing scopes.
If a scope-based rule was intended, express it as required scopes so callers get the actionable InsufficientScopeError instead.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    result = await client.get_prompt(name)
except Exception as e:
    if "insufficient permissions" in str(e):
        # no scope hint available: fall back to another prompt or surface
        # an access-request flow to the user
        result = None
    else:
        raise

Prevention

Prefer scope-based auth on prompts so denials produce actionable 'missing scope' errors.
Document non-scope auth rules (roles/claims/allowlists) for component access.
Test each identity class against every custom auth predicate.
Include the caller's roles/claims checks in CI-level integration tests.

When it happens

Trigger: run_auth_checks_with_shortfall returned (False, []) — e.g. a custom auth predicate/func on the prompt returned False without declaring required scopes, or a non-scope-based AuthProvider rejected the AuthContext for the prompt.

Common situations: Custom `auth` callable on @mcp.prompt rejecting the caller; AuthProvider denies based on claims/roles rather than scopes; token subject not in an allowlist configured on the component.

Related errors

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