Hmbown/CodeWhale · error · anyhow::Error

{} exceeded the {}-page catalogue limit

Error message

{} exceeded the {}-page catalogue limit

What it means

McpCatalogBudget caps paginated catalogue discovery per method: observe_page counts each response and bails once pages exceed MAX_MCP_CATALOG_PAGES = 64 (crates/tui/src/mcp.rs:1280, 1311-1317). The failing method name (tools/list, resources/list, prompts/list) is included. It is a resource-exhaustion guard: the connection aborts during discovery rather than walking an unbounded catalogue.

Source

Thrown at crates/tui/src/mcp.rs:1312

        Self {
            method,
            pages: 0,
            items: 0,
            bytes: 0,
            seen_cursors: HashSet::new(),
        }
    }

    fn observe_page(
        &mut self,
        result: &serde_json::Value,
        item_count: usize,
    ) -> Result<Option<String>> {
        self.pages = self.pages.saturating_add(1);
        self.items = self.items.saturating_add(item_count);
        self.bytes = self.bytes.saturating_add(serde_json::to_vec(result)?.len());
        if self.pages > MAX_MCP_CATALOG_PAGES {
            anyhow::bail!(
                "{} exceeded the {}-page catalogue limit",
                self.method,
                MAX_MCP_CATALOG_PAGES
            );
        }
        if self.items > MAX_MCP_CATALOG_ITEMS {
            anyhow::bail!(
                "{} exceeded the {}-item catalogue limit",
                self.method,
                MAX_MCP_CATALOG_ITEMS
            );
        }
        if self.bytes > MAX_MCP_CATALOG_BYTES {
            anyhow::bail!(
                "{} exceeded the {}-byte aggregate catalogue limit",
                self.method,
                MAX_MCP_CATALOG_BYTES
            );

View on GitHub (pinned to 8880682c63)

Solutions

1. Increase the server's page size so the whole catalogue fits within 64 pages.
2. Reduce the exposed catalogue (disable unused tool groups server-side).
3. Split the gateway into several focused MCP servers, each under the limit.
4. Fix a server that emits near-empty pages while still returning a nextCursor.

Example fix

# before (server): page size 1 with 100 tools -> 100 pages > 64
# after (server): return up to 128 items per page -> 1 page, well under the limit

#!/usr/bin/env bash
# Probe pages before wiring the server in; must stay <= 64 per method.
url="https://mcp.example.com/mcp"; cursor=""; pages=0
while :; do
  body=$(curl -s "$url" -H 'content-type: application/json' \
    -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"${cursor:+,\"params\":{\"cursor\":\"$cursor\"}}}")
  pages=$((pages+1)); [ "$pages" -gt 64 ] && { echo "would exceed 64 pages"; exit 1; }
  cursor=$(printf '%s' "$body" | jq -r '.result.nextCursor // empty');
  [ -z "$cursor" ] && break
done; echo "pages=$pages ok"

When it happens

Trigger: A server paginates one catalogue method into more than 64 pages - e.g. thousands of tools at a small page size, or a server that returns tiny pages with an ever-advancing nextCursor.

Common situations: Mega-gateways exposing thousands of tools; servers configured with page size 1; pagination defaults too small for the catalogue.

Related errors

• {} exceeded the {}-item catalogue limit
• {} exceeded the {}-byte aggregate catalogue limit
• {} repeated pagination cursor; aborting
• Invalid MCP tool name: {prefixed_name}
• Ambiguous MCP tool name '{prefixed_name}' matches more than

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/9808da1ecac19230. Report an issue: GitHub.