alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'serviceName' type String is not present

What it means

Thrown by UpdateClusterForm.validate() when an update-cluster REST request is missing the 'serviceName' parameter. Updating a cluster's health-check configuration requires the owning service to be named, so validate() rejects the call early with HTTP 400 PARAMETER_MISSING. serviceName is the first of several required fields checked in order.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/model/form/UpdateClusterForm.java:54

    
    private String groupName;
    
    private String serviceName;
    
    private String clusterName;
    
    private Integer checkPort;
    
    private Boolean useInstancePort4Check;
    
    private String healthChecker;
    
    private String metadata;
    
    @Override
    public void validate() throws NacosApiException {
        if (StringUtils.isBlank(serviceName)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'serviceName' type String is not present");
        }
        if (StringUtils.isBlank(clusterName)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'clusterName' type String is not present");
        }
        if (null == checkPort) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'checkPort' type Integer is not present");
        }
        if (null == useInstancePort4Check) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'useInstancePort4Check' type Boolean is not present");
        }
        if (StringUtils.isEmpty(healthChecker)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'healthChecker' type String is not present");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Include a non-blank 'serviceName' in the request matching an existing service.
Validate all required fields (serviceName, clusterName, checkPort, useInstancePort4Check, healthChecker) client-side before calling the endpoint.
Check that the service exists in the given namespaceId/groupName first via a service-detail query.

Example fix

// before
UpdateClusterForm form = new UpdateClusterForm();
form.setClusterName("DEFAULT");
// after
form.setServiceName("my-service");
form.setClusterName("DEFAULT");

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isAnyBlank(serviceName, clusterName)) {
    throw new IllegalArgumentException("serviceName and clusterName required");
}
UpdateClusterForm form = new UpdateClusterForm();
form.setServiceName(serviceName);
form.setClusterName(clusterName);
form.setCheckPort(checkPort);
form.setUseInstancePort4Check(useInstancePort4Check);
form.setHealthChecker(healthCheckerJson);

Type guard

static boolean hasClusterUpdateIdentity(String svc, String cluster) {
    return StringUtils.isNotBlank(svc) && StringUtils.isNotBlank(cluster);
}

Prevention

Pre-fill all five required fields in one place before calling the endpoint.
Keep a reusable builder/helper that enforces the required-field contract.
Query the service first to confirm it exists before updating its cluster.

When it happens

Trigger: PUT/POST to the cluster update endpoint (e.g. /v3/admin/ns/cluster or legacy /nacos/v1/ns/cluster) where 'serviceName' is absent or blank while other fields (clusterName, checkPort, etc.) may be present.

Common situations: Calling the cluster-update API after copying a template that omitted serviceName; UI passing only clusterName because the service selector was not bound; scripted bulk cluster updates that forgot the service column.

Related errors

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