{"record":{"id":"9f498916950a0013","repo":"alibaba/nacos","slug":"invalid-version-page-metadata","errorCode":null,"errorMessage":"Invalid Version page metadata","messagePattern":"Invalid Version page metadata","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":142,"sourceCode":"     * @throws IllegalArgumentException when the overview is invalid\n     */\n    public static void validateOverview(AgentOverview overview) {\n        requireNonNull(overview, \"overview\");\n        validateAgent(overview.getAgent());\n        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     */","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L124-L160","documentation":"Thrown by AgentModelValidator.validateVersionSummaryPage as an IllegalArgumentException when the Page metadata is internally inconsistent: totalCount is negative, pageNumber is less than 1, or pagesAvailable is negative. These are impossible/invalid pagination states that indicate a corrupted or misconstructed page object.","triggerScenarios":"Passing a Page<AgentVersionSummary> to validateVersionSummaryPage (directly or via validateOverview) where getTotalCount() < 0, getPageNumber() < 1, or getPagesAvailable() < 0.","commonSituations":"A server response had unset (default 0) page fields deserialized into negative defaults; a pagination builder set pageNumber=0 (1-based index expected); a test constructed a Page with default zeroed metadata.","solutions":["Ensure pageNumber is 1-based (>= 1) and totalCount/pagesAvailable are >= 0 when building the Page.","If the page comes from the server, validate/normalize the metadata before passing it to the validator.","Default missing pagination fields to sane values (pageNumber=1, totalCount=items.size())."],"exampleFix":"// before\nPage<AgentVersionSummary> page = new Page<>();\npage.setPageNumber(0); // invalid\nAgentModelValidator.validateVersionSummaryPage(page); // throws\n\n// after\nPage<AgentVersionSummary> page = new Page<>();\npage.setPageNumber(1);\npage.setTotalCount(items.size());\npage.setPagesAvailable(1);\npage.setPageItems(items);\nAgentModelValidator.validateVersionSummaryPage(page); // ok","handlingStrategy":"validation","validationCode":"static boolean isValidPageMetadata(Page<?> page) {\n    return page.getTotalCount() >= 0 && page.getPageNumber() >= 1 && page.getPagesAvailable() >= 0;\n}\nif (!isValidPageMetadata(page)) {\n    page.setPageNumber(Math.max(1, page.getPageNumber()));\n    page.setTotalCount(Math.max(0, page.getTotalCount()));\n    page.setPagesAvailable(Math.max(0, page.getPagesAvailable()));\n}\nAgentModelValidator.validateVersionSummaryPage(page);","typeGuard":"static boolean hasValidPageMetadata(Page<?> page) {\n    return page.getTotalCount() >= 0 && page.getPageNumber() >= 1 && page.getPagesAvailable() >= 0;\n}","tryCatchPattern":null,"preventionTips":["Always set pageNumber >= 1 (1-based) when constructing a Page.","Default totalCount/pagesAvailable to 0 and pageNumber to 1 rather than leaving them unset.","Validate pagination metadata at the deserialization boundary."],"tags":["java","nacos","ai","agents","validation","pagination"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}