PrefectHQ/fastmcp · error · AuthorizationError

Authorization failed for prompt '{prompt_name}': not found o

Error message

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

What it means

Raised by the authorization middleware's on_get_prompt when a requested prompt cannot be retrieved. Because component-level auth denial and non-existence are deliberately indistinguishable, the message is ambiguous to avoid disclosing the existence of prompts the caller is not authorized to see. It is an AuthorizationError, so the problem is access control, not prompt registration alone.

Source

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

        prompt_name = context.message.name
        fastmcp = context.fastmcp_context
        if fastmcp is None:
            logger.warning(
                f"AuthMiddleware: fastmcp_context is None for prompt '{prompt_name}'. "
                "Denying access for security."
            )
            raise AuthorizationError(
                f"Authorization failed for prompt '{prompt_name}': missing context"
            )

        # get_prompt returns None both when the prompt does not exist and when
        # component-level auth denied access, so the two cases are
        # indistinguishable here. Keep the message ambiguous to avoid
        # disclosing existence of prompts the caller is not authorized to see.
        version = _requested_version(context.message.meta)
        prompt = await fastmcp.fastmcp.get_prompt(prompt_name, version=version)
        if prompt is None:
            raise AuthorizationError(
                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)})"
                    ),
                )

View on GitHub (pinned to 1f02114297)

Solutions

Verify the exact prompt name via prompts/list (as the same authenticated identity) — if it is absent from the list, fix the name or registration.
If the prompt exists but still fails, check the token: is it valid, expired, and does it satisfy the prompt's component-level auth/scope requirements?
Review the middleware's AuthProvider configuration and any auth predicates on the @mcp.prompt decorator to confirm the caller's identity is permitted.
If a specific version was requested via meta, confirm a prompt variant with that version exists.

Example fix

// before: guessing a prompt name
await client.get_prompt("summarize_doc")

// after: confirm it exists and is callable first
prompts = await client.list_prompts()
assert any(p.name == "summarize_doc" for p in prompts)
await client.get_prompt("summarize_doc")

Defensive patterns

Strategy: validation

Validate before calling

prompts = await client.list_prompts()
if not any(p.name == prompt_name for p in prompts):
    raise LookupError(f"prompt '{prompt_name}' not available to this identity")

Try / catch

try:
    result = await client.get_prompt(name)
except Exception as e:
    if "not found or not authorized" in str(e):
        # treat as missing OR forbidden: check list_prompts / credentials
        ...
    raise

Prevention

Discover prompt names via prompts/list instead of hardcoding them.
Keep prompt names and versions in a shared constant/module.
Verify the auth provider grants the intended identity access to each prompt.
When requesting a versioned prompt, confirm the variant exists.

When it happens

Trigger: Calling prompts/get for a prompt_name that (a) does not exist on the server, (b) exists but has component-level auth (e.g. an auth predicate or required scopes) denying the caller, or (c) is filtered out for this identity — all funnel into fastmcp.get_prompt() returning None.

Common situations: Typo in the prompt name; prompt registered under a different name or version than requested; an AuthProvider or per-component auth check denies the caller's token; token expired or lacks the roles the prompt's auth check requires.

Related errors

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