alibaba/nacos · error · NacosApiException

20002

20002

Error message

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

What it means

Thrown by EndpointNaturalKey.of(namespaceId, agentName, protocol, Endpoint) when the endpoint argument is null. The natural key is derived from the Endpoint's URI and transport, so a null Endpoint has no identity to key on. The overloaded of(...) that takes uri+transport does not perform this null check.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecListForm.java:50

    
    @Serial
    private static final long serialVersionUID = 1L;
    
    private String search;
    
    /**
     * Sort field. Supported values: "download_count". Defaults to gmt_modified when null or empty.
     */
    private String orderBy;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        // For list query, agentSpecName is optional
        if (StringUtils.isNotBlank(search)
            && !Constants.AgentSpecs.SEARCH_ACCURATE.equalsIgnoreCase(search)
            && !Constants.AgentSpecs.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;
    }
    
    public String getOrderBy() {
        return orderBy;
    }
    
    public void setOrderBy(String orderBy) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Null-check the Endpoint before calling EndpointNaturalKey.of, or use the (namespaceId, agentName, protocol, uri, transport) overload when you lack an Endpoint object.
2. Filter null Endpoints out of collections before keying.
3. Return Optional/skip when a lookup yields null instead of keying it.

Example fix

// before
EndpointNaturalKey key = EndpointNaturalKey.of(ns, name, proto, endpoint);
// after
if (endpoint == null) {
    continue;
}
EndpointNaturalKey key = EndpointNaturalKey.of(ns, name, proto, endpoint);

if (endpoint == null) {
    throw new IllegalArgumentException("Endpoint must not be null");
}
EndpointNaturalKey.of(namespaceId, agentName, protocol, endpoint);

static boolean hasEndpointIdentity(Endpoint e) {
    return e != null;
}

try {
    EndpointNaturalKey key = EndpointNaturalKey.of(ns, name, proto, endpoint);
} catch (IllegalArgumentException e) {
    // skip null endpoint or return 400
}

When it happens

Trigger: Calling EndpointNaturalKey.of with a null Endpoint, e.g. building identity for a collection entry that was null, or after a failed lookup that returned null.

Common situations: A registry/dedup map built from Endpoints where one source produced null; chaining ofNullable lookups without a guard; misusing the Endpoint-based overload when you only have uri/transport (prefer the other overload).

Related errors

• 10000
• 20002
• 20002
• 10000
• 10000

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