alibaba/nacos · warning · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Console only supports deregistering persistent instances

What it means

Thrown by ConsoleInstanceController.checkDeleteInstanceEphemeral, called from removeInstance (DELETE /v3/console/ns/instance, @Since 3.2.2). It rejects deregistration of ephemeral instances: if instanceForm.getEphemeral() is Boolean.TRUE, it raises NacosApiException with HTTP 400 and ErrorCode.PARAMETER_VALIDATE_ERROR. Ephemeral instances are managed by the client heartbeat/push lifecycle, so the console only deregisters persistent ones.

Source

Thrown at console/src/main/java/com/alibaba/nacos/console/controller/v3/naming/ConsoleInstanceController.java:141

        // build instance
        Instance instance = buildInstance(instanceForm);
        instanceProxy.removeInstance(instanceForm, instance);
        return Result.success("ok");
    }
    
    private void checkWeight(Double weight) throws NacosException {
        if (weight > com.alibaba.nacos.naming.constants.Constants.MAX_WEIGHT_VALUE
            || weight < com.alibaba.nacos.naming.constants.Constants.MIN_WEIGHT_VALUE) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.WEIGHT_ERROR,
                "instance format invalid: The weights range from "
                    + com.alibaba.nacos.naming.constants.Constants.MIN_WEIGHT_VALUE + " to "
                    + com.alibaba.nacos.naming.constants.Constants.MAX_WEIGHT_VALUE);
        }
    }
    
    private void checkDeleteInstanceEphemeral(Boolean ephemeral) throws NacosApiException {
        if (Boolean.TRUE.equals(ephemeral)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Console only supports deregistering persistent instances");
        }
    }
    
    private Instance buildInstance(InstanceForm instanceForm) throws NacosException {
        Instance instance =
            InstanceBuilder.newBuilder().setServiceName(buildCompositeServiceName(instanceForm))
                .setIp(instanceForm.getIp()).setClusterName(instanceForm.getClusterName())
                .setPort(instanceForm.getPort()).setHealthy(instanceForm.getHealthy())
                .setWeight(instanceForm.getWeight()).setEnabled(instanceForm.getEnabled())
                .setMetadata(UtilsAndCommons.parseMetadata(instanceForm.getMetadata()))
                .setEphemeral(instanceForm.getEphemeral()).build();
        if (instanceForm.getEphemeral() == null) {
            // register instance by console default is persistent instance.
            instance.setEphemeral(false);
        }
        return instance;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Deregister ephemeral instances from the owning client/API rather than the console DELETE endpoint.
2. If you must use the console, target a persistent instance (ephemeral=false or null; buildInstance defaults null ephemeral to false).
3. Stop or reconfigure the registering client so it stops heartbeating, then the ephemeral instance expires on its own.

Example fix

// before (ephemeral instance, rejected by console)
form.setEphemeral(true);
instanceProxy.removeInstance(form, instance);

// after (deregister via the owning client instead)
// the client that registered the ephemeral instance should call:
namingService.deregisterInstance(serviceName, ip, port);
// console DELETE only for persistent instances:
form.setEphemeral(false);

// Do not deregister ephemeral instances via console DELETE
Boolean ephemeral = instanceForm.getEphemeral();
if (Boolean.TRUE.equals(ephemeral)) {
    throw new UnsupportedOperationException(
        "Deregister ephemeral instances from the owning client, not the console");
}
controller.removeInstance(instanceForm);

// Java: guard that the instance is persistent before console deregister
boolean consoleDeregisterable = !Boolean.TRUE.equals(instanceForm.getEphemeral());

try {
    controller.removeInstance(form);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()
        && Boolean.TRUE.equals(form.getEphemeral())) {
        // route deregistration to the owning client instead
        namingService.deregisterInstance(svc, ip, port);
    } else { throw e; }
}

When it happens

Trigger: Calling DELETE /v3/console/ns/instance with ephemeral=true (explicitly or because the form defaulted to true).

Common situations: Operator trying to manually remove a service instance from the console that was registered as ephemeral by a client; UI pre-filling ephemeral=true from the instance details.

Related errors

• 10000
• 400
• WEIGHT_ERROR
• 21004
• 400

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