{"record":{"id":"ffac514952c54f50","repo":"PrefectHQ/fastmcp","slug":"self-name-reached-auto-pagination-limit-max-ffac51","errorCode":null,"errorMessage":"[{self.name}] Reached auto-pagination limit ({max_pages} pages) for list_tools. Use list_tools_mcp() with cursor for manual pagination, or increase max_pages.","messagePattern":"\\[(.+?)\\] Reached auto-pagination limit \\((.+?) pages\\) for list_tools\\. Use list_tools_mcp\\(\\) with cursor for manual pagination, or increase max_pages\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/client/mixins/tools.py","lineNumber":135,"sourceCode":"        all_tools: list[mcp_types.Tool] = []\n        cursor: str | None = None\n        seen_cursors: set[str] = set()\n\n        for _ in range(max_pages):\n            result = await self.list_tools_mcp(cursor=cursor, cache_mode=cache_mode)\n            all_tools.extend(result.tools)\n            if not result.next_cursor:\n                break\n            if result.next_cursor in seen_cursors:\n                logger.warning(\n                    f\"[{self.name}] Server returned duplicate pagination cursor\"\n                    f\" {result.next_cursor!r} for list_tools; stopping pagination\"\n                )\n                break\n            seen_cursors.add(result.next_cursor)\n            cursor = result.next_cursor\n        else:\n            raise RuntimeError(\n                f\"[{self.name}] Reached auto-pagination limit\"\n                f\" ({max_pages} pages) for list_tools.\"\n                \" Use list_tools_mcp() with cursor for manual pagination,\"\n                \" or increase max_pages.\"\n            )\n\n        return all_tools\n\n    # --- Call Tool ---\n\n    async def call_tool_mcp(\n        self: Client,\n        name: str,\n        arguments: dict[str, Any],\n        progress_handler: ProgressHandler | None = None,\n        timeout: datetime.timedelta | float | int | None = None,\n        meta: dict[str, Any] | None = None,\n    ) -> mcp_types.CallToolResult:","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/client/mixins/tools.py#L117-L153","documentation":"FastMCP's client `list_tools()` auto-paginates through the server's tool list, following `nextCursor` for up to `max_pages` iterations (default 250). If the cursor chain has not terminated by then, the for-else branch raises `RuntimeError`. This prevents unbounded loops when a server exposes very large tool catalogs or has broken pagination.","triggerScenarios":"Calling `client.list_tools()` against a server exposing more than 250 pages of tools, or a server whose `nextCursor` never becomes None (regenerated or repeated cursors).","commonSituations":"A proxy/gateway aggregating tools from many upstream servers with small page sizes; third-party MCP servers with non-terminating pagination; test servers that always return a cursor.","solutions":["Use `client.list_tools_mcp(cursor=...)` and iterate manually until `result.next_cursor is None`.","Increase the limit: `client.list_tools(max_pages=...)`.","Diagnose the server: if the same cursor repeats, it's a server-side pagination bug to fix or filter around.","Reduce the number of tools registered on the server."],"exampleFix":"// before\ntools = await client.list_tools()  # RuntimeError after 250 pages\n// after\nresult = await client.list_tools_mcp()\ntools = result.tools\nwhile result.next_cursor is not None:\n    result = await client.list_tools_mcp(cursor=result.next_cursor)\n    tools.extend(result.tools)","handlingStrategy":"try-catch","validationCode":"# Probe pagination health before the auto-paginating call\nfirst = await client.list_tools_mcp()\nif first.next_cursor is not None and len(first.tools) < 10:\n    print(\"Server pages are small; prefer manual pagination or larger max_pages\")","typeGuard":null,"tryCatchPattern":"try:\n    tools = await client.list_tools()\nexcept RuntimeError as e:\n    if \"auto-pagination limit\" not in str(e):\n        raise\n    page = await client.list_tools_mcp()\n    tools = page.tools\n    cursor = page.next_cursor\n    while cursor is not None:\n        page = await client.list_tools_mcp(cursor=cursor)\n        tools.extend(page.tools)\n        cursor = page.next_cursor","preventionTips":["Use list_tools_mcp() with an explicit loop when aggregating tools through proxies","Pass an explicit max_pages sized to the expected page count","Detect repeating cursors and stop instead of looping indefinitely","Trim the server's registered tool count when practical"],"tags":["pagination","client","mcp","runtime-error"],"backgroundTag":"pagination-limit-exceeded","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}