alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'serviceName' type String is not present

What it means

Thrown by InstanceMetadataBatchOperationForm.validate() when the 'serviceName' field is blank. This form backs batch instance metadata operations (add/update/delete metadata for multiple instances). The error carries ErrorCode.PARAMETER_MISSING with HTTP 400.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/model/form/InstanceMetadataBatchOperationForm.java:60

    
    private String consistencyType;
    
    private String instances;
    
    private String metadata;
    
    public InstanceMetadataBatchOperationForm() {
    }
    
    /**
     * 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(metadata)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'metadata' 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;
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Provide a non-blank serviceName parameter.
Ensure the SDK or request includes serviceName for batch metadata calls.

Example fix

// before
PUT /v3/admin/ns/instance/metadata/batch?metadata={"env":"prod"}
// after
PUT /v3/admin/ns/instance/metadata/batch?serviceName=my-service&metadata={"env":"prod"}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function hasBatchServiceName(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 for batch metadata operation');
}

Prevention

Populate serviceName when performing batch metadata operations.
Add a client-side pre-flight check.

When it happens

Trigger: Calling a batch metadata operation API without serviceName, or with serviceName='' / whitespace.

Common situations: Client SDK not setting serviceName in a batch metadata request, or a script omitting it.

Related errors

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