alibaba/nacos · error · IllegalArgumentException

versionPage.pageItems exceeds {MAX_VERSION_PAGE_ITEMS} items

Error message

versionPage.pageItems exceeds {MAX_VERSION_PAGE_ITEMS} items

What it means

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.

Source

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

        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
     */
    public static void validateVersionSummary(AgentVersionSummary summary) {
        requireNonNull(summary, "version summary");
        AgentValidationUtils.validateVersion(summary.getVersion());
        validateVersionStatus(summary.getStatus());
        validateOptionalLength(summary.getAuthor(), MAX_AUTHOR_LENGTH, "author");

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Request a smaller page size (<= 100) and paginate through subsequent pages.
2. If building the Page locally, split items into pages of at most 100.
3. Ensure the server-side query limit aligns with this 100-item cap.

Example fix

// before
Page<AgentVersionSummary> page = new Page<>();
page.setPageItems(allVersions); // 150 items
page.setPageNumber(1);
page.setTotalCount(150);
page.setPagesAvailable(2);
AgentModelValidator.validateVersionSummaryPage(page); // throws

// after
List<AgentVersionSummary> first = allVersions.subList(0, 100);
Page<AgentVersionSummary> page = new Page<>();
page.setPageItems(first);
page.setPageNumber(1);
page.setTotalCount(150);
page.setPagesAvailable(2);
AgentModelValidator.validateVersionSummaryPage(page); // ok

static final int MAX_PAGE = 100;
if (pageItems.size() > MAX_PAGE) {
    pageItems = pageItems.subList(0, MAX_PAGE);
}
page.setPageItems(pageItems);
AgentModelValidator.validateVersionSummaryPage(page);

static boolean withinVersionPageLimit(List<?> items) {
    return items != null && items.size() <= 100;
}

When it happens

Trigger: 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.

Common situations: The client requested a pageSize larger than 100; the server did not enforce the cap; a test assembled a page with >100 items.

Related errors

• Invalid Version page metadata
• runtimeEndpointSnapshot.items exceeds {MAX_RUNTIME_ENDPOINTS
• latestVersion must be absent when onlineVersions is empty
• Duplicate online Agent Version: {version.value}
• latestVersion must identify an onlineVersions entry

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