siyuan-note/siyuan · error

tools/list exceeded %d pages

Error message

tools/list exceeded %d pages

What it means

Returned by the MCP `tools/list` paginator when the loop completes `maxMCPToolListPages` (defined as 1000) iterations without the server ever returning an empty `NextCursor`. This is a hard ceiling to prevent unbounded pagination; hitting it means the server keeps advertising more pages beyond a sane limit.

Source

Thrown at kernel/mcp/client/mcp.go:368

	for page := 0; page < maxMCPToolListPages; page++ {
		result, err := listPage(ctx, params)
		if err != nil {
			return nil, err
		}
		if result == nil {
			return nil, fmt.Errorf("tools/list returned an empty response")
		}
		allTools = append(allTools, result.Tools...)
		if result.NextCursor == "" {
			return allTools, nil
		}
		if _, exists := seenCursors[result.NextCursor]; exists {
			return nil, fmt.Errorf("tools/list repeated cursor %q", result.NextCursor)
		}
		seenCursors[result.NextCursor] = struct{}{}
		params = &mcp.ListToolsParams{Cursor: result.NextCursor}
	}
	return nil, fmt.Errorf("tools/list exceeded %d pages", maxMCPToolListPages)
}

func sanitizedServerNameCollision(server conf.MCPServer) bool {
	mcpMu.Lock()
	defer mcpMu.Unlock()
	sanitizedName := sanitize(server.Name)
	for _, configured := range mcpServers {
		if configured.ID != server.ID && sanitize(configured.Name) == sanitizedName {
			return true
		}
	}
	return false
}

func mcpToolName(server conf.MCPServer, toolName string, collision bool) string {
	name := "mcp_" + sanitize(server.Name) + "_" + sanitize(toolName)
	if !collision && len(name) <= maxMCPToolNameLen {
		return name

View on GitHub (pinned to 251596fc0d)

Solutions

1. Patch the server to terminate pagination with an empty `NextCursor` once all tools are listed.
2. Confirm the server is not in an error state that prevents it from finishing the listing.
3. If you genuinely need a higher ceiling, raise `maxMCPToolListPages` in `kernel/mcp/client/mcp.go` after auditing memory and latency implications.

Example fix

// before (server side)
return { tools, nextCursor: cursor + 1 } // never ends
// after
if noMoreTools {
    return { tools, nextCursor: "" } // terminate
}

tools, err := listAllTools(ctx, client.ListTools)
if err != nil && strings.Contains(err.Error(), "exceeded") {
    // server never terminates pagination; cap or disable it
    return err
}

When it happens

Trigger: A server that always returns a non-empty `NextCursor` (without repeating it, which would trip the repeated-cursor guard) and never signals the end of the tool list, forcing the client to stop after 1000 pages.

Common situations: A misbehaving MCP server generating unbounded cursors; an extremely large tool catalog that legitimately exceeds 1000 pages (unlikely — 1000 pages is far beyond any real catalog); a server bug where the terminal empty cursor is never emitted.

Related errors

• tools/list repeated cursor %q
• tools/list returned an empty response
• connect: %w
• OAuth callback did not include an authorization code
• image attachment request limit exceeded: at most %d images a

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/bf2c68a7bee28084. Report an issue: GitHub.