What causes "Invalid Version page metadata" in alibaba/nacos?

Ensure pageNumber is 1-based (>= 1) and totalCount/pagesAvailable are >= 0 when building the Page.

alibaba/nacos · error · IllegalArgumentException

Invalid Version page metadata

Error message

Invalid Version page metadata

What it means

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.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:142

     * @throws IllegalArgumentException when the overview is invalid
     */
    public static void validateOverview(AgentOverview overview) {
        requireNonNull(overview, "overview");
        validateAgent(overview.getAgent());
        validateVersionSummaryPage(overview.getVersionPage());
    }
    
    /**
     * Validate an Agent Version summary page.
     *
     * @param page Agent Version summary page
     * @throws IllegalArgumentException when the page is invalid
     */
    public static void validateVersionSummaryPage(Page<AgentVersionSummary> page) {
        requireNonNull(page, "versionPage");
        if (page.getTotalCount() < 0 || page.getPageNumber() < 1
            || page.getPagesAvailable() < 0) {
            throw new IllegalArgumentException("Invalid Version page metadata");
        }
        List<AgentVersionSummary> pageItems = page.getPageItems();
        requireNonNull(pageItems, "versionPage.pageItems");
        if (pageItems.size() > MAX_VERSION_PAGE_ITEMS) {
            throw new IllegalArgumentException(
                "versionPage.pageItems exceeds " + MAX_VERSION_PAGE_ITEMS + " items");
        }
        for (AgentVersionSummary summary : pageItems) {
            validateVersionSummary(summary);
        }
    }
    
    /**
     * Validate one Agent Version summary.
     *
     * @param summary Agent Version summary
     * @throws IllegalArgumentException when the summary is invalid
     */

View on GitHub (pinned to 9b989acdf1)

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()).

Example fix

// before
Page<AgentVersionSummary> page = new Page<>();
page.setPageNumber(0); // invalid
AgentModelValidator.validateVersionSummaryPage(page); // throws

// after
Page<AgentVersionSummary> page = new Page<>();
page.setPageNumber(1);
page.setTotalCount(items.size());
page.setPagesAvailable(1);
page.setPageItems(items);
AgentModelValidator.validateVersionSummaryPage(page); // ok

Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidPageMetadata(Page<?> page) {
    return page.getTotalCount() >= 0 && page.getPageNumber() >= 1 && page.getPagesAvailable() >= 0;
}
if (!isValidPageMetadata(page)) {
    page.setPageNumber(Math.max(1, page.getPageNumber()));
    page.setTotalCount(Math.max(0, page.getTotalCount()));
    page.setPagesAvailable(Math.max(0, page.getPagesAvailable()));
}
AgentModelValidator.validateVersionSummaryPage(page);

Type guard

static boolean hasValidPageMetadata(Page<?> page) {
    return page.getTotalCount() >= 0 && page.getPageNumber() >= 1 && page.getPagesAvailable() >= 0;
}

Prevention

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.

When it happens

Trigger: Passing a Page<AgentVersionSummary> to validateVersionSummaryPage (directly or via validateOverview) where getTotalCount() < 0, getPageNumber() < 1, or getPagesAvailable() < 0.

Common situations: 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.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/9f498916950a0013. Report an issue: GitHub.