What causes "{} exceeded the {}-item catalogue limit" in Hmbown/CodeWhale?

Trim the server's exposed tools/resources below the item limit

exceeded the -item catalogue limit

Error message

{} exceeded the {}-item catalogue limit

What it means

The MCP catalogue tracker also caps the total number of items (individual tools/resources across all pages) at MAX_MCP_CATALOG_ITEMS. This error is thrown when cumulative item count crosses that limit, independent of page count. Like the page cap it defends against unbounded catalogue responses flooding memory and the model context.

Solutions

Trim the server's exposed tools/resources below the item limit
Raise MAX_MCP_CATALOG_ITEMS if the large catalogue is trusted and desired
Split the catalogue across multiple MCP servers with smaller, focused tool sets

Defensive patterns

Strategy: try-catch

Try / catch

match discovery_result {
    Err(e) if e.to_string().contains("-item catalogue limit") => {
        eprintln!("Server exposes more items than allowed; split the server or raise MAX_MCP_CATALOG_ITEMS.");
    }
    Ok(catalogue) => use_catalogue(catalogue),
    other => other?,
}

Prevention

Split gateway servers aggregating many backends into separate, smaller MCP servers
Only enable tools you actually use (server-side filtering) to stay under the item cap
Track item counts in your own tooling when aggregating multiple MCP servers into one client

When it happens

Trigger: track() accumulates item_count per result page and bails when self.items > MAX_MCP_CATALOG_ITEMS — a server whose aggregate catalogue exceeds the item ceiling, even if pages stay within MAX_MCP_CATALOG_PAGES.

Common situations: Server exposing thousands of tools/resources; a gateway aggregating many backend servers into one huge catalogue; compact limits set for context-budget reasons exceeded by a legitimately large server.

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

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

Appendix: source

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

    }

    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
            );
        }
        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())

View on GitHub (pinned to 73e0f67d83)