Hmbown/CodeWhale · error

exceeded the -page catalogue limit

Error message

{} exceeded the {}-page catalogue limit

What it means

MCP catalogue discovery responses are capped at MAX_MCP_CATALOG_PAGES pages. This budget-tracker method counts pages as results stream in and bails once the page count exceeds the configured maximum. It protects the client from a malicious or broken server that streams unbounded pagination (resource exhaustion, prompt/context flooding).

Solutions

1. Reduce the number of tools the MCP server exposes so it fits within the page limit
2. Configure/raise MAX_MCP_CATALOG_PAGES if your server legitimately needs a larger catalogue and you trust it
3. Investigate the server if pagination seems unbounded — endless pages can indicate a bug or attack

# Estimate catalogue size before connecting: ask the server how many pages it advertises,
# or sample tools/list and extrapolate. There is no pre-call API — guard the call instead.

match discovery_result {
    Err(e) if e.to_string().contains("-page catalogue limit") => {
        eprintln!("Server catalogue too large for configured limits; reduce exposed tools or raise MAX_MCP_CATALOG_PAGES.");
    }
    Ok(catalogue) => use_catalogue(catalogue),
    other => other?,
}

When it happens

Trigger: The discovery accumulator's track method increments self.pages on every result page; it bails when pages > MAX_MCP_CATALOG_PAGES — i.e. the server returned more paginated responses than allowed for the method.

Common situations: A server with an enormous tool catalogue paginating hundreds of results; a misbehaving or compromised server that never stops returning pages; a very low catalogue limit configured for an intentionally tiny plugin environment.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• exceeded the -item catalogue limit
• JSON-RPC line exceeded the
• MCP config exceeds the 1 MiB limit
• MCP consent history exceeds size limit
• MCP exceeded its overall deadline

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/9808da1ecac19230. Report an issue: GitHub.

Appendix: source

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

        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 73e0f67d83)