PrefectHQ/fastmcp · error · RuntimeError

[{self.name}] Reached auto-pagination limit ({max_pages} pag

Error message

[{self.name}] Reached auto-pagination limit ({max_pages} pages) for list_prompts. Use list_prompts_mcp() with cursor for manual pagination, or increase max_pages.

What it means

FastMCP's client `list_prompts()` auto-paginates through the server's prompt list, following `nextCursor` for up to `max_pages` iterations (default 250, `AUTO_PAGINATION_MAX_PAGES`). If the cursor chain does not terminate within that budget, the for-else branch raises `RuntimeError` instead of looping forever. It is a safety guard against runaway or non-terminating pagination, not a server failure.

Source

Thrown at fastmcp_slim/fastmcp/client/mixins/prompts.py:110

        all_prompts: list[mcp_types.Prompt] = []
        cursor: str | None = None
        seen_cursors: set[str] = set()

        for _ in range(max_pages):
            result = await self.list_prompts_mcp(cursor=cursor)
            all_prompts.extend(result.prompts)
            if not result.next_cursor:
                break
            if result.next_cursor in seen_cursors:
                logger.warning(
                    f"[{self.name}] Server returned duplicate pagination cursor"
                    f" {result.next_cursor!r} for list_prompts; stopping pagination"
                )
                break
            seen_cursors.add(result.next_cursor)
            cursor = result.next_cursor
        else:
            raise RuntimeError(
                f"[{self.name}] Reached auto-pagination limit"
                f" ({max_pages} pages) for list_prompts."
                " Use list_prompts_mcp() with cursor for manual pagination,"
                " or increase max_pages."
            )

        return all_prompts

    # --- Prompt ---
    async def get_prompt_mcp(
        self: Client,
        name: str,
        arguments: dict[str, Any] | None = None,
        meta: dict[str, Any] | None = None,
    ) -> mcp_types.GetPromptResult:
        """Send a prompts/get request and return the complete MCP protocol result.

        Args:

View on GitHub (pinned to 1f02114297)

Solutions

Use the low-level `client.list_prompts_mcp(cursor=...)` and iterate manually, stopping when `result.next_cursor is None`.
Raise the budget: `client.list_prompts(max_pages=...)` with a larger value.
Fix or avoid the server that emits non-terminating cursors; verify with `list_prompts_mcp()` whether the same cursor is repeated.
Reduce the number of prompts on the server or ask the server to return larger pages.

Example fix

// before
prompts = await client.list_prompts()  # RuntimeError after 250 pages
// after
result = await client.list_prompts_mcp()
prompts = result.prompts
while result.next_cursor is not None:
    result = await client.list_prompts_mcp(cursor=result.next_cursor)
    prompts.extend(result.prompts)

Defensive patterns

Strategy: try-catch

Validate before calling

# Probe pagination health before the auto-paginating call
first = await client.list_prompts_mcp()
if first.next_cursor is not None and len(first.prompts) < 10:
    print("Server pages are small; prefer manual pagination or larger max_pages")

Try / catch

try:
    prompts = await client.list_prompts()
except RuntimeError as e:
    if "auto-pagination limit" not in str(e):
        raise
    # fall back to manual pagination
    page = await client.list_prompts_mcp()
    prompts = page.prompts
    cursor = page.next_cursor
    while cursor is not None:
        page = await client.list_prompts_mcp(cursor=cursor)
        prompts.extend(page.prompts)
        cursor = page.next_cursor

Prevention

Use list_prompts_mcp() with an explicit loop when the server is known to have large catalogs
Pass an explicit max_pages sized to the expected catalog size (pages, not items)
Log next_cursor values when debugging so a repeating (broken) cursor is obvious
Watch for servers that emit a cursor even on the final page

When it happens

Trigger: Calling `client.list_prompts()` (or the internal `_send` path) against a server that returns more than 250 pages of prompts, or a misbehaving server whose `nextCursor` never becomes None (e.g. a cursor that repeats or is always regenerated).

Common situations: Connecting to a proxy/gateway server that exposes a very large upstream prompt catalog split into tiny pages; a buggy third-party MCP server that fails to terminate its cursor chain; a page size of ~1 item on a server with hundreds of prompts.

Related errors

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