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

What it means

FastMCP's client `list_resources()` auto-paginates through the server's resource list, following `nextCursor` for up to `max_pages` iterations (default 250). If the cursor chain does not terminate within that budget, the for-else branch raises `RuntimeError`. This guards against infinite loops caused by very large catalogs or servers that never clear `nextCursor`.

Source

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

        all_resources: list[mcp_types.Resource] = []
        cursor: str | None = None
        seen_cursors: set[str] = set()

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

        return all_resources

    async def list_resource_templates_mcp(
        self: Client,
        *,
        cursor: str | None = None,
        cache_mode: CacheMode = "use",
    ) -> mcp_types.ListResourceTemplatesResult:
        """Send a resources/listResourceTemplates request and return the complete MCP protocol result.

        Args:
            cursor: Optional pagination cursor from a previous request's nextCursor.

View on GitHub (pinned to 1f02114297)

Solutions

Switch to `client.list_resources_mcp(cursor=...)` and page manually until `result.next_cursor is None`.
Pass a larger `max_pages` to `client.list_resources(max_pages=...)`.
Inspect `list_resources_mcp()` output to check whether the server repeats the same cursor (server bug) — stop on repeated cursors in your own loop.
Reduce the resource count or page size on the server side.

Example fix

// before
resources = await client.list_resources()  # RuntimeError after 250 pages
// after
result = await client.list_resources_mcp()
resources = result.resources
while result.next_cursor is not None:
    result = await client.list_resources_mcp(cursor=result.next_cursor)
    resources.extend(result.resources)

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

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

Prevention

Use list_resources_mcp() with an explicit loop for very large resource catalogs
Pass an explicit max_pages matched to the expected number of pages
Detect repeating cursors in your own loop and bail out early
Verify server pagination terminates correctly before relying on auto-pagination

When it happens

Trigger: Calling `client.list_resources()` against a server exposing more than 250 pages of resources, or a server whose `nextCursor` never becomes None (repeated/regenerated cursors).

Common situations: Pointing a client at a gateway that aggregates thousands of resources with small page sizes; a third-party MCP server with a broken pagination implementation; running against a mock/test server that always returns a cursor.

Related errors

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