PrefectHQ/fastmcp · error · ValueError

Unknown transport: {transport}

Error message

Unknown transport: {transport}

What it means

FastMCP.run_async() validates the transport name against the fixed set {stdio, http, sse, streamable-http} before dispatching. Any other value raises ValueError('Unknown transport: ...').

Source

Thrown at fastmcp_slim/fastmcp/server/mixins/transport.py:92

    async def run_async(
        self: FastMCP,
        transport: Transport | None = None,
        show_banner: bool | None = None,
        **transport_kwargs: Any,
    ) -> None:
        """Run the FastMCP server asynchronously.

        Args:
            transport: Transport protocol to use ("stdio", "http", "sse", or "streamable-http")
            show_banner: Whether to display the server banner. If None, uses the
                FASTMCP_SHOW_SERVER_BANNER setting (default: True).
        """
        if show_banner is None:
            show_banner = fastmcp.settings.show_server_banner
        if transport is None:
            transport = fastmcp.settings.transport
        if transport not in {"stdio", "http", "sse", "streamable-http"}:
            raise ValueError(f"Unknown transport: {transport}")

        if transport == "stdio":
            await self.run_stdio_async(
                show_banner=show_banner,
                **transport_kwargs,
            )
        elif transport in {"http", "sse", "streamable-http"}:
            await self.run_http_async(
                transport=transport,
                show_banner=show_banner,
                **transport_kwargs,
            )
        else:
            raise ValueError(f"Unknown transport: {transport}")

    def run(
        self: FastMCP,
        transport: Transport | None = None,

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass one of 'stdio', 'http', 'sse', 'streamable-http' as transport
2. Fix the FASTMCP_TRANSPORT environment variable or the settings file if transport defaults from settings
3. Use 'http' for the modern streamable HTTP transport

Example fix

// before
server.run(transport='streamable_http')

// after
server.run(transport='streamable-http')

VALID = {'stdio', 'http', 'sse', 'streamable-http'}
transport = transport or fastmcp.settings.transport
if transport not in VALID:
    raise ValueError(f'Unsupported transport {transport!r}; choose from {sorted(VALID)}')

try:
    await server.run_async(transport=transport)
except ValueError as e:
    if 'Unknown transport' in str(e):
        logger.error(f'Bad transport config: {e}; falling back to stdio')
        await server.run_async(transport='stdio')
    else:
        raise

When it happens

Trigger: Calling server.run_async(transport='websocket') or passing an invalid string, or having fastmcp.settings.transport (env FASTMCP_TRANSPORT) set to an unrecognized value with transport=None.

Common situations: Typo like 'streamable_http' or 'https'; environment variable FASTMCP_TRANSPORT set to a legacy/unsupported name; copying transport names from other frameworks.

Related errors

• cache_ttl must be a positive integer, got {cache_ttl}
• SSE transport does not support stateless mode
• Invalid transport: {transport}
• cache_ttl_seconds must be non-negative, got {ttl_seconds}
• max_cache_size must be non-negative, got {max_size}

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