alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'serviceName' type String is not present

What it means

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

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/model/form/InstanceForm.java:71

    
    private Boolean enabled;
    
    private String metadata;
    
    private Boolean ephemeral;
    
    public InstanceForm() {
    }
    
    /**
     * 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");
        }
        if (StringUtils.isBlank(ip)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'ip' type String is not present");
        }
        if (port == null) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'port' type Integer is not present");
        }
    }
    
    /**
     * fill default value.
     */
    public void fillDefaultValue() {
        if (StringUtils.isBlank(namespaceId)) {
            namespaceId = Constants.DEFAULT_NAMESPACE_ID;

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Provide a non-blank serviceName parameter.
  2. Verify the SDK or HTTP client includes serviceName in the request.

Example fix

// before
POST /v3/client/ns/instance?ip=10.0.0.1&port=8080
// after
POST /v3/client/ns/instance?serviceName=my-service&ip=10.0.0.1&port=8080
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function hasInstanceServiceName(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

When it happens

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

Common situations: Client SDK not setting serviceName, or a curl/script omitting the parameter.

Related errors

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