PrefectHQ/fastmcp · error · AuthenticationRequiredError

Horizon authentication is required

Error message

Horizon authentication is required

What it means

whoami() loads the session snapshot and, if no credential (API key) is stored, raises AuthenticationRequiredError('Horizon authentication is required') instead of calling the user endpoint without auth.

Source

Thrown at fastmcp_slim/fastmcp/cli/deploy/command.py:315

        "login",
        user,
        json_output=json_output,
    )


async def whoami(
    *,
    json_output: JsonOption = False,
) -> None:
    """Show the current Prefect Horizon user."""
    credentials = CredentialStore()
    configuration: HorizonConfiguration | None = None
    credential: ResolvedCredential | None = None

    try:
        configuration, credential = _load_session_snapshot(credentials)
        if credential is None:
            raise AuthenticationRequiredError("Horizon authentication is required")
        user = await _get_user(
            configuration.api_origin,
            credential,
        )
    except HorizonUnauthorizedError as error:
        if (
            configuration is not None
            and credential is not None
            and credential.source == "stored"
        ):
            try:
                credentials.clear_if_matches(
                    credential.api_key,
                    expected_api_origin=configuration.api_origin,
                )
            except StateFileError as cleanup_error:
                _fail_for_expected_error(
                    "whoami",

View on GitHub (pinned to 1f02114297)

Solutions

1. Run `fastmcp deploy login` to authenticate, then retry whoami
2. Verify the credentials file exists at the expected path (check HOME/env differences)
3. In scripts, call login() programmatically before whoami()

Example fix

// before
user = await whoami(credentials)  # AuthenticationRequiredError
// after
await login(client, host=host)
user = await whoami(credentials)

from pathlib import Path
cred_path = Path.home() / ".fastmcp" / "horizon-credentials.json"
logged_in = cred_path.exists()

from fastmcp.cli.deploy.command import AuthenticationRequiredError
try:
    user = await whoami(credentials)
except AuthenticationRequiredError:
    await login(host=host)
    user = await whoami(credentials)

When it happens

Trigger: Running `fastmcp deploy whoami` (or calling whoami) before ever running `login`, or after the credentials file was deleted/corrupted such that no credential resolved.

Common situations: Fresh machines/CI environments without logged-in sessions; manually cleared credentials; HOME differences between shells pointing at a different credentials path.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• FastMCP CLI support is not installed. Install `fastmcp` or `
• Expected integer, got {raw!r}
• Expected number, got {raw!r}
• Expected boolean, got {raw!r}
• Expected JSON {schema_type}, got {raw!r}

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