{"record":{"id":"ad27785f312e5828","repo":"alibaba/nacos","slug":"versionpage-pageitems-exceeds-max-version-page-it","errorCode":null,"errorMessage":"versionPage.pageItems exceeds {MAX_VERSION_PAGE_ITEMS} items","messagePattern":"versionPage\\.pageItems exceeds (.+?) items","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":147,"sourceCode":"        validateVersionSummaryPage(overview.getVersionPage());\n    }\n    \n    /**\n     * Validate an Agent Version summary page.\n     *\n     * @param page Agent Version summary page\n     * @throws IllegalArgumentException when the page is invalid\n     */\n    public static void validateVersionSummaryPage(Page<AgentVersionSummary> page) {\n        requireNonNull(page, \"versionPage\");\n        if (page.getTotalCount() < 0 || page.getPageNumber() < 1\n            || page.getPagesAvailable() < 0) {\n            throw new IllegalArgumentException(\"Invalid Version page metadata\");\n        }\n        List<AgentVersionSummary> pageItems = page.getPageItems();\n        requireNonNull(pageItems, \"versionPage.pageItems\");\n        if (pageItems.size() > MAX_VERSION_PAGE_ITEMS) {\n            throw new IllegalArgumentException(\n                \"versionPage.pageItems exceeds \" + MAX_VERSION_PAGE_ITEMS + \" items\");\n        }\n        for (AgentVersionSummary summary : pageItems) {\n            validateVersionSummary(summary);\n        }\n    }\n    \n    /**\n     * Validate one Agent Version summary.\n     *\n     * @param summary Agent Version summary\n     * @throws IllegalArgumentException when the summary is invalid\n     */\n    public static void validateVersionSummary(AgentVersionSummary summary) {\n        requireNonNull(summary, \"version summary\");\n        AgentValidationUtils.validateVersion(summary.getVersion());\n        validateVersionStatus(summary.getStatus());\n        validateOptionalLength(summary.getAuthor(), MAX_AUTHOR_LENGTH, \"author\");","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L129-L165","documentation":"Thrown by validateVersionSummaryPage as an IllegalArgumentException when page.getPageItems() contains more than MAX_VERSION_PAGE_ITEMS (100) entries. This enforces a bounded page size so a single overview payload stays within resource limits.","triggerScenarios":"Passing a version summary page whose pageItems list size exceeds 100. Happens when the page size was set too large or the caller loaded all versions into one page.","commonSituations":"The client requested a pageSize larger than 100; the server did not enforce the cap; a test assembled a page with >100 items.","solutions":["Request a smaller page size (<= 100) and paginate through subsequent pages.","If building the Page locally, split items into pages of at most 100.","Ensure the server-side query limit aligns with this 100-item cap."],"exampleFix":"// before\nPage<AgentVersionSummary> page = new Page<>();\npage.setPageItems(allVersions); // 150 items\npage.setPageNumber(1);\npage.setTotalCount(150);\npage.setPagesAvailable(2);\nAgentModelValidator.validateVersionSummaryPage(page); // throws\n\n// after\nList<AgentVersionSummary> first = allVersions.subList(0, 100);\nPage<AgentVersionSummary> page = new Page<>();\npage.setPageItems(first);\npage.setPageNumber(1);\npage.setTotalCount(150);\npage.setPagesAvailable(2);\nAgentModelValidator.validateVersionSummaryPage(page); // ok","handlingStrategy":"validation","validationCode":"static final int MAX_PAGE = 100;\nif (pageItems.size() > MAX_PAGE) {\n    pageItems = pageItems.subList(0, MAX_PAGE);\n}\npage.setPageItems(pageItems);\nAgentModelValidator.validateVersionSummaryPage(page);","typeGuard":"static boolean withinVersionPageLimit(List<?> items) {\n    return items != null && items.size() <= 100;\n}","tryCatchPattern":null,"preventionTips":["Keep page size at or below 100 when requesting version summaries.","Paginate rather than loading all versions into one response.","Assert page item count in tests against the documented 100-item cap."],"tags":["java","nacos","ai","agents","validation","pagination","capacity"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}