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_resource_templates. Use list_resource_templates_mcp() with cursor for manual pagination, or increase max_pages.

What it means

FastMCP's client `list_resource_templates()` auto-paginates through URI templates, following `nextCursor` for up to `max_pages` iterations (default 250). If pagination does not terminate in time, the for-else branch raises `RuntimeError`. Same safety guard as the other list methods, applied to resource templates.

Source

Thrown at fastmcp_slim/fastmcp/client/mixins/resources.py:206

        cursor: str | None = None
        seen_cursors: set[str] = set()

        for _ in range(max_pages):
            result = await self.list_resource_templates_mcp(cursor=cursor)
            all_templates.extend(result.resource_templates)
            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_resource_templates;"
                    " 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_resource_templates."
                " Use list_resource_templates_mcp() with cursor for manual pagination,"
                " or increase max_pages."
            )

        return all_templates

    async def read_resource_mcp(
        self: Client, uri: AnyUrl | str, meta: dict[str, Any] | None = None
    ) -> mcp_types.ReadResourceResult:
        """Send a resources/read request and return the complete MCP protocol result.

        Args:
            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.

        Returns:

View on GitHub (pinned to 1f02114297)

Solutions

Use `client.list_resource_templates_mcp(cursor=...)` and loop manually until `result.next_cursor is None`.
Increase the budget: `client.list_resource_templates(max_pages=...)`.
Check the server's cursor behavior — a repeated cursor means a server-side pagination bug to fix or work around.
Consolidate templates server-side so fewer pages are needed.

Example fix

// before
templates = await client.list_resource_templates()  # RuntimeError after 250 pages
// after
result = await client.list_resource_templates_mcp()
templates = result.resource_templates
while result.next_cursor is not None:
    result = await client.list_resource_templates_mcp(cursor=result.next_cursor)
    templates.extend(result.resource_templates)

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

try:
    templates = await client.list_resource_templates()
except RuntimeError as e:
    if "auto-pagination limit" not in str(e):
        raise
    page = await client.list_resource_templates_mcp()
    templates = page.resource_templates
    cursor = page.next_cursor
    while cursor is not None:
        page = await client.list_resource_templates_mcp(cursor=cursor)
        templates.extend(page.resource_templates)
        cursor = page.next_cursor

Prevention

Use list_resource_templates_mcp() with an explicit loop for template-heavy servers
Pass an explicit max_pages sized to the expected page count
Log cursors during development to spot non-terminating chains
Consolidate templates server-side so pagination stays shallow

When it happens

Trigger: Calling `client.list_resource_templates()` against a server with more than 250 pages of templates, or one whose `nextCursor` never resolves to None.

Common situations: A server generating templates dynamically per-entity (thousands of templates); gateway/proxy setups with tiny page sizes; buggy servers that keep emitting cursors.

Related errors

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