{"record":{"id":"198ba0dbffb10582","repo":"hs-web/hsweb-framework","slug":"error-page-size-exceeded","errorCode":"error.page_size_exceeded","errorMessage":"error.page_size_exceeded","messagePattern":"error\\.page_size_exceeded","errorType":"validation","errorClass":"ValidationException.NoStackTrace","httpStatus":400,"severity":"warning","filePath":"hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/PagerQueryPolicy.java","lineNumber":140,"sourceCode":"        return maxPageSize;\n    }\n\n    public OverflowPolicy getOverflowPolicy() {\n        return overflowPolicy;\n    }\n\n    private int handleOverflow(int requestedPageSize) {\n        return switch (overflowPolicy) {\n            case WARN -> {\n                // 兼容已发布的大页调用；告警只包含数量，不记录查询条件或业务数据。\n                log.warn(\n                    \"Requested pageSize [{}] exceeds configured maxPageSize [{}], preserving it because overflow policy is WARN\",\n                    requestedPageSize,\n                    maxPageSize);\n                yield requestedPageSize;\n            }\n            case CLAMP -> maxPageSize;\n            case REJECT -> throw new ValidationException.NoStackTrace(\n                \"pageSize\",\n                \"error.page_size_exceeded\",\n                requestedPageSize,\n                maxPageSize);\n        };\n    }\n\n    private static int resolveDefaultMaxPageSize() {\n        return Integer.getInteger(\n            MAX_PAGE_SIZE_PROPERTY,\n            Integer.getInteger(LEGACY_MAX_PAGE_SIZE_PROPERTY, DEFAULT_MAX_PAGE_SIZE));\n    }\n\n    private static OverflowPolicy resolveDefaultOverflowPolicy() {\n        String value = System.getProperty(OVERFLOW_POLICY_PROPERTY, OverflowPolicy.WARN.name());\n        try {\n            return OverflowPolicy.valueOf(value.trim().toUpperCase(Locale.ROOT));\n        } catch (IllegalArgumentException error) {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/hs-web/hsweb-framework/blob/b2cfc85a57c70bf5b5cf6e7edae2d37102652ec8/hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/query/PagerQueryPolicy.java#L122-L158","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Reduce the requested pageSize to <= the configured maxPageSize.","Change the overflow policy to CLAMP or WARN if rejecting is too strict for your use case (PagerQueryPolicy config).","Increase maxPageSize in configuration if large pages are legitimate.","Catch ValidationException and map error.page_size_exceeded to HTTP 400 with a friendly message."],"exampleFix":"// before\nPagerQuery query = PagerQuery.of(1, 100000); // exceeds max, REJECT policy\n\n// after\nint safeSize = Math.min(requestedSize, policy.getMaxPageSize());\nPagerQuery query = PagerQuery.of(1, safeSize);","handlingStrategy":"validation","validationCode":"// Java\nPagerQueryPolicy policy = ...;\nif (query.getPageSize() > policy.getMaxPageSize()) {\n    query.setPageSize(policy.getMaxPageSize()); // or reject before calling the API\n}","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n    pagerQuery(query);\n} catch (ValidationException.NoStackTrace e) {\n    if (\"error.page_size_exceeded\".equals(e.getCode())) {\n        throw new BadRequestException(\"pageSize exceeds max \" + e.getValues().toArray());\n    }\n    throw e;\n}","preventionTips":["Clamp client-supplied page sizes at the API boundary.","Document maxPageSize for API consumers.","Pick the overflow policy (WARN/CLAMP/REJECT) deliberately per environment."],"tags":["java","pagination","validation","page-size"],"backgroundTag":"value-out-of-range","analyzedSha":"b2cfc85a57c70bf5b5cf6e7edae2d37102652ec8","analyzedAt":"2026-09-13T09:05:02.172Z","contentChangedAt":"2026-09-13T09:05:02.172Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}