alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'serviceName' type String is not present

What it means

Thrown by ServiceForm.validate() when a service create/update REST request omits or leaves blank the 'serviceName' parameter. Nacos needs serviceName to identify the target service, so the controller rejects the request with HTTP 400 (ErrorCode.PARAMETER_MISSING) before any business logic runs. It is a pure client-side input-validation error.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/model/form/ServiceForm.java:58

    
    private String groupName;
    
    private Boolean ephemeral;
    
    private Float protectThreshold;
    
    private String metadata;
    
    private String selector;
    
    public ServiceForm() {
    }
    
    @Override
    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 (ephemeral == null) {
            ephemeral = false;
        }
        if (protectThreshold == null) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Supply a non-blank 'serviceName' value in the request query string or form body.
If building the request programmatically, assert org.apache.commons.lang3.StringUtils.isNotBlank(serviceName) before sending.
Confirm the field name matches exactly ('serviceName'); some clients send 'serviceName' vs 'name'.

Example fix

// before
curl -X POST 'http://host:8848/nacos/v1/ns/service' -d 'groupName=DEFAULT_GROUP'
// after
curl -X POST 'http://host:8848/nacos/v1/ns/service' -d 'serviceName=my-service&groupName=DEFAULT_GROUP'

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(serviceName)) {
    throw new IllegalArgumentException("serviceName must not be blank");
}
ServiceForm form = new ServiceForm();
form.setServiceName(serviceName);

Type guard

static boolean hasValidServiceName(String s) {
    return s != null && !s.trim().isEmpty();
}

Prevention

Always populate serviceName from a non-null source before constructing the form.
Add a unit test that asserts validate() passes for a minimal valid form.
Log the full form fields client-side before sending to surface missing params early.

When it happens

Trigger: POST/PUT to the service management endpoint (e.g. /v3/admin/ns/service or legacy /nacos/v1/ns/service) where the query/form body has an empty, blank, or missing 'serviceName' field. The controller binds the form and calls validate(); fillDefaultValue() runs first but only defaults namespaceId/groupName, never serviceName.

Common situations: Frontend service form submitted with an empty name field; a maintainer-client or curl command that dropped the serviceName flag; a parameter renamed by mistake (e.g. 'name' instead of 'serviceName'); an SDK call where serviceName was never set.

Related errors

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