What causes "AgentSpec name is required" in alibaba/nacos?

Add the `name` query parameter to the GET request.

alibaba/nacos · error · NacosApiException

10000

10000

Error message

AgentSpec name is required

What it means

Thrown by AgentSpecQueryForm.validate() when the `name` field is blank. This is the client-runtime GET endpoint used by agents/SDKs to fetch an online AgentSpec by version/label. Unlike the admin forms it does NOT extend AgentSpecForm; namespaceId defaults to 'public' but name is mandatory. Maps to code 10000 (PARAMETER_MISSING), HTTP 400.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/client/AgentSpecQueryForm.java:51

    private String name;
    
    private String version;
    
    private String label;
    
    private String md5;
    
    /**
     * Validate and normalize query parameters.
     *
     * @throws NacosApiException if required parameters are missing
     */
    public void validate() throws NacosApiException {
        if (StringUtils.isBlank(namespaceId)) {
            namespaceId = Constants.AgentSpecs.AGENTSPEC_DEFAULT_NAMESPACE;
        }
        if (StringUtils.isBlank(name)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "AgentSpec name is required");
        }
    }
    
    public String getNamespaceId() {
        return namespaceId;
    }
    
    public void setNamespaceId(String namespaceId) {
        this.namespaceId = namespaceId;
    }
    
    public String getName() {
        return name;
    }
    
    public void setName(String name) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Add the `name` query parameter to the GET request.
If using a config-driven name, verify the env/config value is non-empty before the call.
Note this endpoint expects `name`, not `agentSpecName` — match the exact field.

Example fix

// before
curl 'http://host/v3/admin/ai/agentspecs?version=latest'
// after
curl 'http://host/v3/admin/ai/agentspecs?name=mySpec&version=latest'

Defensive patterns

Strategy: validation

Validate before calling

if (name == null || name.trim().isEmpty()) {
    throw new IllegalArgumentException("AgentSpec name is required");
}

Type guard

static boolean hasName(String n) {
    return n != null && !n.trim().isEmpty();
}

Try / catch

catch (NacosApiException e) {
    if (e.getErrCode() == 10000 && e.getMessage().contains("AgentSpec name")) { /* supply name */ }
}

Prevention

Remember the client endpoint uses `name`, not agentSpecName.
Resolve the agentspec name from config before the runtime fetch.

When it happens

Trigger: Calling GET /v3/admin/ai/agentspecs (the client OPEN_API, anonymous-allowed) without the `name` query parameter. Supports optional version/label/md5 for conditional get.

Common situations: An agent SDK or RAD client fetches an agentspec before the name is configured; misconfigured environment variable yields an empty name; the caller passes the name under a different key (e.g. agentSpecName) instead of `name`.

Related errors

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