alibaba/nacos · error · NacosApiException

10000

10000

Error message

Request parameter `agentSpecName` should not be blank.

What it means

Thrown by EndpointCanonicalizer.canonicalize when endpoint.getPriority() is non-null and negative. A null priority defaults to 0; an explicit non-negative value is accepted; only a strictly negative integer is rejected. Priority influences Endpoint selection ordering.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecLabelsUpdateForm.java:45

 * AgentSpec labels update form.
 *
 * @author nacos
 */
public class AgentSpecLabelsUpdateForm extends AgentSpecForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    /**
     * JSON string: {"stable":"v2"}. The reserved label "latest" is managed by server.
     */
    private String labels;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        if (StringUtils.isBlank(getAgentSpecName())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `agentSpecName` should not be blank.");
        }
        if (StringUtils.isBlank(labels)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `labels` should not be blank.");
        }
    }
    
    public String getLabels() {
        return labels;
    }
    
    public void setLabels(String labels) {
        this.labels = labels;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Use null (or omit the field) to get the default priority of 0, or set a non-negative integer.
Replace any -1 'unset' sentinel with null at the boundary.
Clamp computed priorities to >=0 before submission.

Example fix

// before
endpoint.setPriority(-1);
// after
endpoint.setPriority(null); // defaults to 0

Defensive patterns

Strategy: validation

Validate before calling

Integer p = endpoint.getPriority();
if (p != null && p < 0) {
    throw new IllegalArgumentException("Endpoint priority must not be negative");
}

Type guard

static boolean isValidPriority(Integer p) {
    return p == null || p >= 0;
}

Try / catch

try {
    Endpoint canon = EndpointCanonicalizer.canonicalize(endpoint);
} catch (IllegalArgumentException e) {
    // return 400, priority out of range
}

Prevention

Use null (not -1) to mean 'default priority'.
Clamp computed priorities to >=0.

When it happens

Trigger: Submitting an Endpoint with priority set to a negative number (e.g. -1) through any path that canonicalizes the Endpoint before persistence/push.

Common situations: Using -1 as a sentinel for 'default' (the code treats null, not -1, as default); sign errors in priority computation; configs that use negative numbers for 'lowest'.

Related errors

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