What causes "tools/list repeated cursor %q" in siyuan-note/siyuan?

Fix the server so each `NextCursor` is unique and the final page returns an empty `NextCursor` to terminate pagination.

tools/list repeated cursor %q

Error message

tools/list repeated cursor %q

What it means

Returned by the MCP `tools/list` paginator when the same `NextCursor` value appears twice across pages. The helper keeps a `seenCursors` set precisely to detect servers that return a cursor pointing back to a page already fetched, which would otherwise loop forever; a repeat is treated as a protocol violation.

Source

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

	var (
		allTools []*mcp.Tool
		params   *mcp.ListToolsParams
	)
	seenCursors := map[string]struct{}{}
	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
}

View on GitHub (pinned to 251596fc0d)

Solutions

Fix the server so each `NextCursor` is unique and the final page returns an empty `NextCursor` to terminate pagination.
Update the MCP server library/version if the bug is known upstream.
If testing, ensure your stub advances cursors and eventually signals completion.

Defensive patterns

Strategy: try-catch

Try / catch

tools, err := listAllTools(ctx, client.ListTools)
if err != nil && strings.Contains(err.Error(), "repeated cursor") {
    // server has a pagination bug; disable or report it
    return err
}

Prevention

Prefer well-maintained MCP server libraries with correct pagination.
When building a server, ensure each cursor is unique and the last page sends an empty cursor.
Log the repeated cursor value to pinpoint the server bug.

When it happens

Trigger: An MCP server returns a `NextCursor` equal to one it already returned, e.g. always echoing the same cursor, or cycling through a fixed set without termination. The detection triggers on the second occurrence of any cursor.

Common situations: A buggy or non-conformant MCP server; a pagination implementation that forgets to clear the cursor on the last page; a mocked/stub server used in testing that returns a static cursor.

Related errors

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