alibaba/nacos · error · NacosApiException

10000

10000

Error message

Request parameter `agentSpecName` should not be blank.

What it means

Thrown by Instance.validate() (HTTP 400, NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING) when the 'ip' field is blank after fillDefaultValue(). The naming Instance model requires a non-blank ip for registration; this is the legacy/service-discovery Instance, distinct from the AI Endpoint model. validate() is called during instance register/update APIs.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecPublishForm.java:51

    @Serial
    private static final long serialVersionUID = 1L;
    
    private String version;
    
    /**
     * Legacy latest label update flag.
     *
     * @deprecated since 3.3.0, the latest label is managed by the server. This
     * parameter is ignored and retained only for compatibility with legacy clients.
     */
    @Deprecated(since = "3.3.0")
    private Boolean updateLatestLabel;
    
    @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(version)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `version` should not be blank.");
        }
    }
    
    @Override
    public String getVersion() {
        return version;
    }
    
    @Override
    public void setVersion(String version) {
        this.version = version;
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set a non-blank ip (IPv4/IPv6/hostname as the API expects) before registering the Instance.
2. Null/blank-check ip at the client before the register call.
3. If registering by service name only, use the correct API/overload rather than leaving ip blank.

Example fix

// before
Instance inst = new Instance();
inst.setPort(8080);
naming.registerInstance(serviceName, inst);
// after
Instance inst = new Instance();
inst.setIp("10.0.0.5");
inst.setPort(8080);
naming.registerInstance(serviceName, inst);

if (org.apache.commons.lang3.StringUtils.isBlank(instance.getIp())) {
    throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
        "Required parameter 'ip' type String is not present");
}

static boolean hasInstanceIp(Instance i) {
    return i != null && i.getIp() != null && !i.getIp().trim().isEmpty();
}

try {
    instance.validate();
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM) {
        // surface 400 to client with missing 'ip'
    }
}

When it happens

Trigger: Calling a naming instance register or update API (Open API /v3/client/ns/instance or equivalent) with ip unset, empty, or whitespace-only. The Instance.validate() hook runs at the controller/service boundary.

Common situations: A client constructing an Instance and forgetting setIp; a form bind that loses the ip parameter; whitespace from a config; registering an instance from a hostname-only source where ip was not resolved.

Related errors

• PARAMETER_MISSING
• PARAMETER_MISSING
• PARAMETER_MISSING
• PARAMETER_MISSING
• 400

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