hs-web/hsweb-framework · warning · ValidationException.NoStackTrace

error.page_size_exceeded

error.page_size_exceeded

Error message

error.page_size_exceeded

What it means

PagerQueryPolicy.validatePageSize enforces a configured maxPageSize. Under the REJECT overflow policy, when the requested pageSize exceeds the maximum, it throws ValidationException.NoStackTrace with code error.page_size_exceeded instead of silently clamping or warning. The library lets deployments choose WARN (allow, log), CLAMP (shrink), or REJECT (fail) behavior.

Solutions

1. Reduce the requested pageSize to <= the configured maxPageSize.
2. Change the overflow policy to CLAMP or WARN if rejecting is too strict for your use case (PagerQueryPolicy config).
3. Increase maxPageSize in configuration if large pages are legitimate.
4. Catch ValidationException and map error.page_size_exceeded to HTTP 400 with a friendly message.

Example fix

// before
PagerQuery query = PagerQuery.of(1, 100000); // exceeds max, REJECT policy

// after
int safeSize = Math.min(requestedSize, policy.getMaxPageSize());
PagerQuery query = PagerQuery.of(1, safeSize);

// Java
PagerQueryPolicy policy = ...;
if (query.getPageSize() > policy.getMaxPageSize()) {
    query.setPageSize(policy.getMaxPageSize()); // or reject before calling the API
}

// Java
try {
    pagerQuery(query);
} catch (ValidationException.NoStackTrace e) {
    if ("error.page_size_exceeded".equals(e.getCode())) {
        throw new BadRequestException("pageSize exceeds max " + e.getValues().toArray());
    }
    throw e;
}

When it happens

Trigger: Calling PagerQuery / QueryHelper paging APIs with pageSize larger than the configured maxPageSize while the pager overflow policy is set to REJECT (policy configured via PagerQueryPolicy/overflow config).

Common situations: Client sends huge page sizes (e.g. pageSize=100000) to 'fetch everything'; deployment hardened policy to REJECT after previously allowing CLAMP; frontend hardcodes a page size larger than server max; version upgrade introduced the policy with defaults callers didn't expect.

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

• parentId
• 不支持的验证规则:
• 不支持的授权请求:
• unsupported dialect :
• join class [" + clazz + "] not found!

AI-assisted analysis of hs-web/hsweb-framework@b2cfc85a57 (2026-09-13). Data as JSON: /api/errors/198ba0dbffb10582. Report an issue: GitHub.

Appendix: source

Thrown at hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/PagerQueryPolicy.java:140

        return maxPageSize;
    }

    public OverflowPolicy getOverflowPolicy() {
        return overflowPolicy;
    }

    private int handleOverflow(int requestedPageSize) {
        return switch (overflowPolicy) {
            case WARN -> {
                // 兼容已发布的大页调用；告警只包含数量，不记录查询条件或业务数据。
                log.warn(
                    "Requested pageSize [{}] exceeds configured maxPageSize [{}], preserving it because overflow policy is WARN",
                    requestedPageSize,
                    maxPageSize);
                yield requestedPageSize;
            }
            case CLAMP -> maxPageSize;
            case REJECT -> throw new ValidationException.NoStackTrace(
                "pageSize",
                "error.page_size_exceeded",
                requestedPageSize,
                maxPageSize);
        };
    }

    private static int resolveDefaultMaxPageSize() {
        return Integer.getInteger(
            MAX_PAGE_SIZE_PROPERTY,
            Integer.getInteger(LEGACY_MAX_PAGE_SIZE_PROPERTY, DEFAULT_MAX_PAGE_SIZE));
    }

    private static OverflowPolicy resolveDefaultOverflowPolicy() {
        String value = System.getProperty(OVERFLOW_POLICY_PROPERTY, OverflowPolicy.WARN.name());
        try {
            return OverflowPolicy.valueOf(value.trim().toUpperCase(Locale.ROOT));
        } catch (IllegalArgumentException error) {

View on GitHub (pinned to b2cfc85a57)