What causes "Page size must not exceed %s" in SonarSource/sonarqube?

Reduce ps to at most RESULTS_MAX_SIZE (use ps=100 or less)

SonarSource/sonarqube · error · IllegalArgumentException

Page size must not exceed

Error message

Page size must not exceed %s

What it means

Validation guard in SearchTemplatesAction.validatePaginationParameters: the permission templates search WS call received a 'ps' (page size) parameter larger than the maximum allowed page size (the %s is the configured MAX_PAGE_SIZE). It fires before authorization and DB access, so callers must reduce the requested page size; nothing is wrong on the server side.

Solutions

Reduce ps to at most RESULTS_MAX_SIZE (use ps=100 or less)
Implement proper pagination using the paging.nextPageToken/total in the response instead of one huge page
Clamp the page size client-side before the request

Example fix

// before
await searchTemplates({ ps: 1000 });

// after
const MAX_PS = 100;
await searchTemplates({ ps: Math.min(requestedPs, MAX_PS) });

Defensive patterns

Strategy: validation

Validate before calling

const MAX_PS = 100;
if (ps > MAX_PS) ps = MAX_PS;
await searchTemplates({ ps });

Type guard

function isWithinMaxPageSize(ps, max) { return ps == null || (Number.isInteger(ps) && ps <= max); }

Try / catch

try { await searchTemplates({ ps }); } catch (e) { if (e.message.includes('must not exceed')) { return searchTemplates({ ps: 100 }); } throw e; }

Prevention

Clamp ps to the server maximum before requesting
Paginate with repeated smaller pages instead of one large page
Do not assume one endpoint's max page size applies to all endpoints

When it happens

Trigger: GET api/permissions/search_templates with ps greater than RESULTS_MAX_SIZE (e.g. ps=1000 when max is 100); clients that always send a large default page size.

Common situations: Bulk-export scripts requesting everything in one call; SDK defaults larger than server maximums; confusion between server-side max page size limits across SonarQube endpoints.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/80bbf6bc7b3a8301. Report an issue: GitHub.

Appendix: source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/permission/ws/template/SearchTemplatesAction.java:126

        .setQuery(wsRequest.param(Param.TEXT_QUERY))
        .setPage(wsRequest.paramAsInt(Param.PAGE))
        .setPageSize(wsRequest.paramAsInt(Param.PAGE_SIZE));

      validatePaginationParameters(request);
      checkGlobalAdmin(userSession);

      SearchTemplatesWsResponse searchTemplatesWsResponse = buildResponse(load(dbSession, request));
      writeProtobuf(searchTemplatesWsResponse, wsRequest, wsResponse);
    }
  }

  private static void validatePaginationParameters(SearchTemplatesRequest request) {
    if (request.getPageSize() != null) {
      if (request.getPageSize() < 0) {
        throw new IllegalArgumentException("Page size must be >= 0");
      }
      if (request.getPageSize() > RESULTS_MAX_SIZE) {
        throw new IllegalArgumentException("Page size must not exceed " + RESULTS_MAX_SIZE);
      }
    }
  }

  private static void buildDefaultTemplatesResponse(SearchTemplatesWsResponse.Builder response, SearchTemplatesData data) {
    TemplateIdQualifier.Builder templateUuidQualifierBuilder = TemplateIdQualifier.newBuilder();

    ResolvedDefaultTemplates resolvedDefaultTemplates = data.defaultTemplates();
    response.addDefaultTemplates(templateUuidQualifierBuilder
      .setQualifier(ComponentQualifiers.PROJECT)
      .setTemplateId(resolvedDefaultTemplates.getProject()));

    resolvedDefaultTemplates.getApplication()
      .ifPresent(viewDefaultTemplate -> response.addDefaultTemplates(
        templateUuidQualifierBuilder
          .clear()
          .setQualifier(ComponentQualifiers.APP)
          .setTemplateId(viewDefaultTemplate)));

View on GitHub (pinned to 184c821202)