github/github-mcp-server · error

perPage value %d exceeds maximum of 100

Error message

perPage value %d exceeds maximum of 100

What it means

Returned by CursorPaginationParams.ToGraphQLParams when perPage exceeds 100. GitHub's GraphQL API enforces a hard ceiling of 100 items per page on first/last arguments, and this validation fails fast before a doomed request is sent. The value flows from the per_page tool argument into cursor-based GraphQL pagination (ProjectsV2, etc.).

Source

Thrown at pkg/github/params.go:477

	HasNextPage     bool   `json:"hasNextPage"`
	HasPreviousPage bool   `json:"hasPreviousPage"`
	NextCursor      string `json:"nextCursor,omitempty"`
	PrevCursor      string `json:"prevCursor,omitempty"`
}

func buildPageInfo(resp *github.Response) pageInfo {
	return pageInfo{
		HasNextPage:     resp.After != "",
		HasPreviousPage: resp.Before != "",
		NextCursor:      resp.After,
		PrevCursor:      resp.Before,
	}
}

// ToGraphQLParams converts cursor pagination parameters to GraphQL-specific parameters.
func (p CursorPaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
	if p.PerPage > 100 {
		return nil, fmt.Errorf("perPage value %d exceeds maximum of 100", p.PerPage)
	}
	if p.PerPage < 0 {
		return nil, fmt.Errorf("perPage value %d cannot be negative", p.PerPage)
	}
	first := int32(p.PerPage)

	var after *string
	if p.After != "" {
		after = &p.After
	}

	return &GraphQLPaginationParams{
		First: &first,
		After: after,
	}, nil
}

type GraphQLPaginationParams struct {

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Set per_page to 100 or lower for GraphQL-backed tools
2. Omit per_page entirely and let the server default apply
3. Make the limit data-driven per tool (REST vs GraphQL) instead of one global constant
4. If you need more than 100 items, follow pagination cursors (pageInfo.nextCursor/after) across multiple calls

Example fix

// before
{"per_page":200}
// after
{"per_page":100}

const maxGraphQLPerPage = 100
func clampPerPage(n int) int {
    if n > maxGraphQLPerPage {
        return maxGraphQLPerPage
    }
    if n < 0 {
        return 0
    }
    return n
}
// before building the call:
args["per_page"] = clampPerPage(requestedPerPage)

func isValidPerPage(n int) bool {
    return n >= 0 && n <= 100
}

gqlParams, err := cursor.ToGraphQLParams()
if err != nil {
    if strings.Contains(err.Error(), "exceeds maximum") {
        gqlParams, _ = (&github.CursorPaginationParams{PerPage: 100, After: cursor.After}).ToGraphQLParams()
    } else {
        return err
    }
}

When it happens

Trigger: Calling a GraphQL-backed tool (e.g. list_project_items, search via GraphQL path) with per_page > 100; a client defaulting page size to 200; chaining a REST-tuned pagination config (REST allows up to 100 per page for many endpoints) into a GraphQL-backed tool.

Common situations: Porting scripts from REST endpoints where higher limits were accepted; configuration shared across tools where one tool's max differs; teams standardizing on a large page size hitting the first GraphQL-backed tool.

Related errors

• perPage value %d cannot be negative
• installation token response did not contain a token
• installation token response did not contain an expiry
• OAuth callback listener could not bind
• failed to get issue ID: %w

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/19c6c1a7d4c7c46b. Report an issue: GitHub.