What causes "Parameter 'offset' must >= 0" in alibaba/nacos?

Send offset >= 0 (the first page is offset 0).

alibaba/nacos · error · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Parameter 'offset' must >= 0

What it means

ListServerForm validates pagination for the ARD list-servers endpoint. offset must be non-negative; a negative offset throws PARAMETER_VALIDATE_ERROR (HTTP 400).

Source

Thrown at ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/form/ListServerForm.java:90

    }
    
    public String getSearchMode() {
        return searchMode;
    }
    
    public void setSearchMode(String searchMode) {
        this.searchMode = searchMode;
    }
    
    /**
     * check form parameters while valid.
     *
     * @throws NacosApiException when form parameters is invalid.
     */
    @Override
    public void validate() throws NacosApiException {
        if (offset < 0) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Parameter 'offset' must >= 0");
        }
        
        if (limit > Constants.MAX_LIST_SIZE) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Parameter 'limit' must <= 100");
        }
        
        if (StringUtils.isNotEmpty(searchMode)) {
            if (!Constants.MCP_LIST_SEARCH_BLUR.equals(searchMode)
                && !Constants.MCP_LIST_SEARCH_ACCURATE.equals(searchMode)) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_MISMATCH,
                    "Parameter 'searchMode' must be " + Constants.MCP_LIST_SEARCH_BLUR + " or "
                        + Constants.MCP_LIST_SEARCH_ACCURATE);
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

Send offset >= 0 (the first page is offset 0).
Clamp the computed offset to 0 before the call.
Check that your page index is 1-based (or 0-based) consistently with the formula.

Example fix

// before
int offset = (page - 1) * size; // page can be 0 -> offset = -size

// after
int page = Math.max(page, 1);
int offset = (page - 1) * size;

Defensive patterns

Strategy: validation

Validate before calling

int page = Math.max(pageArg, 1);
int offset = (page - 1) * pageSize;
if (offset < 0) throw new IllegalArgumentException("offset must be >= 0");
uri.queryParam("offset", offset);

Prevention

Treat the first page as offset 0.
Clamp computed offsets to 0.
Unit-test pagination math at page=0 and page=1.

When it happens

Trigger: Calling the list-servers endpoint with ?offset set to a negative number (e.g. -1).

Common situations: Computing offset as (page-1)*pageSize when page is 0 or negative; arithmetic underflow; defaulting an unset page to -1.

Related errors

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