alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'serviceName' type String is not present

What it means

Thrown by InstanceListForm.validate() when the 'serviceName' field is blank. This form backs instance list/query APIs (batch instance retrieval). The error carries ErrorCode.PARAMETER_MISSING with HTTP 400.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/model/form/InstanceListForm.java:55

    private String namespaceId;
    
    private String groupName;
    
    private String serviceName;
    
    private String clusterName;
    
    private Boolean healthyOnly;
    
    /**
     * check param.
     *
     * @throws NacosApiException NacosApiException
     */
    public void validate() throws NacosApiException {
        fillDefaultValue();
        if (StringUtils.isBlank(serviceName)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'serviceName' type String is not present");
        }
    }
    
    /**
     * fill default value.
     */
    public void fillDefaultValue() {
        if (StringUtils.isBlank(namespaceId)) {
            namespaceId = Constants.DEFAULT_NAMESPACE_ID;
        }
        if (StringUtils.isBlank(groupName)) {
            groupName = Constants.DEFAULT_GROUP;
        }
        if (StringUtils.isBlank(clusterName)) {
            clusterName = StringUtils.EMPTY;
        }
        if (null == healthyOnly) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Provide a non-blank serviceName parameter.
Ensure the SDK includes serviceName in the list request.

Example fix

// before
GET /v3/client/ns/instance/list?namespaceId=public&groupName=DEFAULT_GROUP
// after
GET /v3/client/ns/instance/list?namespaceId=public&groupName=DEFAULT_GROUP&serviceName=my-service

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(serviceName)) {
    throw new IllegalArgumentException("serviceName is required for instance list");
}

Type guard

function hasListServiceName(form: { serviceName?: string }): boolean {
  return typeof form.serviceName === 'string' && form.serviceName.trim().length > 0;
}

Try / catch

// Validate before API call
if (!form.serviceName?.trim()) {
  throw new Error('serviceName is required');
}

Prevention

Always provide serviceName when listing instances.
Validate in the client SDK before the HTTP call.

When it happens

Trigger: Calling an instance list API (e.g. GET /v3/client/ns/instance/list) without serviceName, or with serviceName='' / whitespace.

Common situations: Client SDK not setting serviceName before the list call, or a script omitting it.

Related errors

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