alibaba/nacos · error · NacosApiException

20002

20002

Error message

Request parameter `search` should be `accurate` or `blur`.

What it means

Thrown by AgentValidationUtils.validateNonLatestLabel when a client-supplied label equals the reserved string 'latest'. 'latest' is server-managed (it points at the working version) and cannot be written, moved, or deleted by clients. The basic validateLabel accepts 'latest', so this dedicated guard enforces the reservation.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/a2a/admin/AgentListForm.java:43

/**
 * Agent list form.
 *
 * @author KiteSoar
 */
public class AgentListForm extends AgentForm {
    
    @Serial
    private static final long serialVersionUID = 4706219418699928980L;
    
    private String search;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        if (!Constants.MCP_LIST_SEARCH_ACCURATE.equalsIgnoreCase(search)
            && !Constants.MCP_LIST_SEARCH_BLUR.equalsIgnoreCase(search)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Request parameter `search` should be `accurate` or `blur`.");
        }
    }
    
    public String getSearch() {
        return search;
    }
    
    public void setSearch(String search) {
        this.search = search;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Use a concrete version label (e.g. '1.0.0', 'stable') instead of 'latest'.
  2. Filter 'latest' out of any client-provided label set before submission.
  3. Treat 'latest' as read-only in client SDKs; never send it on write operations.

Example fix

// before
labels.put("latest", targetVersion);
// after
labels.put("1.0.0", targetVersion);
Defensive patterns

Strategy: validation

Validate before calling

if ("latest".equals(label)) {
    throw new IllegalArgumentException("The latest label is server-managed");
}
AgentValidationUtils.validateNonLatestLabel(label);

Type guard

static boolean isClientWritableLabel(String s) {
    return s != null && !"latest".equals(s)
        && s.matches("^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$");
}

Try / catch

try {
    AgentValidationUtils.validateNonLatestLabel(label);
} catch (IllegalArgumentException e) {
    // return 400; tell client 'latest' is server-managed
}

Prevention

When it happens

Trigger: Posting a label reference or catalog entry whose label is 'latest' through RadModelValidator.validateNonLatestLabel (line 187) — e.g. trying to pin or move the 'latest' pointer from a client API.

Common situations: A client hard-coding 'latest' as a default label; tooling that mirrors all labels including the server-managed one; attempting to 'reset' a deployment by writing latest.

Related errors

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