alibaba/nacos · error · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

cursor must be >= 0

What it means

ListServersOfficialForm.resolveOffset parses the cursor string as an integer offset. A value that parses but is negative throws PARAMETER_VALIDATE_ERROR (HTTP 400).

Source

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

    public void setUpdatedSince(String updatedSince) {
        this.updatedSince = updatedSince;
    }
    
    /**
     * 解析 cursor 字段为 offset 数值.
     * 当 cursor 为空时返回 0；当为非法数字时抛出 NacosApiException.
     *
     * @return offset 数值
     * @throws NacosApiException 当 cursor 非法或为负数
     */
    public int resolveOffset() throws NacosApiException {
        if (cursor == null || cursor.isEmpty()) {
            return 0;
        }
        try {
            int off = Integer.parseInt(cursor);
            if (off < 0) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_VALIDATE_ERROR, "cursor must be >= 0");
            }
            return off;
        } catch (NumberFormatException e) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR, "cursor must be numeric");
        }
    }
    
    @Override
    public void validate() throws NacosApiException {
        if (limit == null) {
            limit = DEFAULT_LIMIT;
        }
        if (limit < 0) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR, "limit must be >= 0");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Send a non-negative cursor (start at 0).
2. Echo back the server-returned pageToken/cursor verbatim rather than recomputing it.
3. Clamp any computed cursor to 0.

Example fix

// before
GET /servers?cursor=-10

// after
GET /servers?cursor=0

int off = cursor == null || cursor.isEmpty() ? 0 : Integer.parseInt(cursor);
if (off < 0) throw new IllegalArgumentException("cursor must be >= 0");
uri.queryParam("cursor", off);

When it happens

Trigger: Calling the official list-servers endpoint with ?cursor=-1 or any negative numeric cursor.

Common situations: Reusing a cursor token that was decremented; computing the next cursor from a negative offset; defaulting an empty cursor to -1.

Related errors

• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISMATCH
• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING
• Invalid Version page metadata

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