Hmbown/CodeWhale · error · anyhow::Error

{} exceeded the {}-byte aggregate catalogue limit

Error message

{} exceeded the {}-byte aggregate catalogue limit

What it means

Third leg of McpCatalogBudget: the sum of serde-serialized page sizes across one catalogue method must stay within MAX_MCP_CATALOG_BYTES = 32 MiB (crates/tui/src/mcp.rs:1282, 1325-1331). Each page's JSON is serialized and its byte length accumulated; crossing 32 MiB aborts discovery. This bounds memory and prompt-bloat from very verbose catalogue entries.

Source

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

        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
            );
        }
        let cursor = result
            .get("nextCursor")
            .and_then(|value| value.as_str())
            .map(str::to_owned);
        if let Some(cursor) = cursor.as_ref()
            && !self.seen_cursors.insert(cursor.clone())
        {
            anyhow::bail!("{} repeated pagination cursor; aborting", self.method);
        }
        Ok(cursor)
    }
}

View on GitHub (pinned to 8880682c63)

Solutions

1. Shorten tool/resource descriptions and trim JSON Schemas server-side.
2. Split the catalogue across multiple MCP servers so each stays under 32 MiB aggregate.
3. Remove example payloads and verbose metadata from catalogue entries.

Example fix

# before (server): each tool carries a ~10 KB description -> 3500 tools ~ 35 MB
# after (server): cap descriptions at ~500 chars -> aggregate well under 32 MiB

#!/usr/bin/env bash
# Probe aggregate serialized bytes; must stay <= 33554432 (32 MiB) per method.
url="https://mcp.example.com/mcp"; cursor=""; bytes=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\"}}}")
  bytes=$((bytes + $(printf '%s' "$body" | jq -c '.result' | wc -c)))
  [ "$bytes" -gt 33554432 ] && { echo "would exceed 32 MiB"; exit 1; }
  cursor=$(printf '%s' "$body" | jq -r '.result.nextCursor // empty');
  [ -z "$cursor" ] && break
done; echo "bytes=$bytes ok"

When it happens

Trigger: Fewer than 4096 items but each very large: multi-KB descriptions, embedded schemas or examples in tool definitions push the aggregate past 32 MiB.

Common situations: Auto-generated tool descriptions from OpenAPI specs; servers embedding full JSON Schemas with long examples per tool.

Related errors

• {} exceeded the {}-page catalogue limit
• {} exceeded the {}-item catalogue limit
• {} repeated pagination cursor; aborting
• MCP SSE frame exceeded {} bytes without a separator — aborti
• MCP response Content-Length {len} exceeds {} bytes — abortin

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