PrefectHQ/fastmcp · error · ValueError

Unknown format: {format}

Error message

Unknown format: {format}

What it means

`format_info` only supports the formats accepted by the `inspect` utility (e.g. 'mcp' and 'fastmcp'); any other string falls through the if/elif chain to a ValueError. It is a fail-fast guard against misspelled or unsupported output format arguments.

Source

Thrown at fastmcp_slim/fastmcp/utilities/inspect.py:532

    Returns:
        JSON bytes in the requested format
    """
    # Convert string to enum if needed
    if isinstance(format, str):
        format = InspectFormat(format)

    if format == InspectFormat.MCP:
        # MCP format doesn't need FastMCPInfo, it uses Client directly
        return await format_mcp_info(mcp)
    elif format == InspectFormat.FASTMCP:
        # For FastMCP format, we need the FastMCPInfo
        # This works for both v1 and v2 servers
        if info is None:
            info = await inspect_fastmcp(mcp)
        return format_fastmcp_info(info)
    else:
        raise ValueError(f"Unknown format: {format}")

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass a supported format value ('mcp' or 'fastmcp' — check the inspect utility's accepted set).
2. Normalize/validate user input against the allowed formats before calling.
3. Add explicit handling for the desired format upstream if a new output style is needed.

Example fix

// before
info = await format_info(mcp, fmt='json')
// after
info = await format_info(mcp, format='fastmcp')

SUPPORTED_FORMATS = {'mcp', 'fastmcp'}
def check_format(fmt: str):
    if fmt not in SUPPORTED_FORMATS:
        raise ValueError(f'format must be one of {sorted(SUPPORTED_FORMATS)}, got {fmt!r}')

from typing import Literal
Format = Literal['mcp', 'fastmcp']
def is_valid_format(fmt: str) -> TypeGuard[Format]:
    return fmt in ('mcp', 'fastmcp')

try:
    info = await format_info(mcp, format=fmt)
except ValueError:
    info = await format_info(mcp, format='mcp')

When it happens

Trigger: Calling `format_info(mcp, format='json')`, `format='yaml'`, or a typo like `format='fastMcp'` instead of a supported format string.

Common situations: Building CLI flags or config that pass user-provided format names straight into `format_info`; case-sensitivity mistakes ('FastMCP' vs 'fastmcp').

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• cache_scope requires cache_ttl; a scope without a TTL does n
• Total must be at least 1
• Amount must be at least 1
• Version string cannot contain '@' (used as key delimiter): {
• meta['fastmcp'] must be a dict

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