{"record":{"id":"b286847e580792de","repo":"alibaba/nacos","slug":"parameter-validate-error-b28684","errorCode":"PARAMETER_VALIDATE_ERROR","errorMessage":"Console only supports deregistering persistent instances","messagePattern":"Console only supports deregistering persistent instances","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"console/src/main/java/com/alibaba/nacos/console/controller/v3/naming/ConsoleInstanceController.java","lineNumber":141,"sourceCode":"        // build instance\n        Instance instance = buildInstance(instanceForm);\n        instanceProxy.removeInstance(instanceForm, instance);\n        return Result.success(\"ok\");\n    }\n    \n    private void checkWeight(Double weight) throws NacosException {\n        if (weight > com.alibaba.nacos.naming.constants.Constants.MAX_WEIGHT_VALUE\n            || weight < com.alibaba.nacos.naming.constants.Constants.MIN_WEIGHT_VALUE) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.WEIGHT_ERROR,\n                \"instance format invalid: The weights range from \"\n                    + com.alibaba.nacos.naming.constants.Constants.MIN_WEIGHT_VALUE + \" to \"\n                    + com.alibaba.nacos.naming.constants.Constants.MAX_WEIGHT_VALUE);\n        }\n    }\n    \n    private void checkDeleteInstanceEphemeral(Boolean ephemeral) throws NacosApiException {\n        if (Boolean.TRUE.equals(ephemeral)) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Console only supports deregistering persistent instances\");\n        }\n    }\n    \n    private Instance buildInstance(InstanceForm instanceForm) throws NacosException {\n        Instance instance =\n            InstanceBuilder.newBuilder().setServiceName(buildCompositeServiceName(instanceForm))\n                .setIp(instanceForm.getIp()).setClusterName(instanceForm.getClusterName())\n                .setPort(instanceForm.getPort()).setHealthy(instanceForm.getHealthy())\n                .setWeight(instanceForm.getWeight()).setEnabled(instanceForm.getEnabled())\n                .setMetadata(UtilsAndCommons.parseMetadata(instanceForm.getMetadata()))\n                .setEphemeral(instanceForm.getEphemeral()).build();\n        if (instanceForm.getEphemeral() == null) {\n            // register instance by console default is persistent instance.\n            instance.setEphemeral(false);\n        }\n        return instance;","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/console/src/main/java/com/alibaba/nacos/console/controller/v3/naming/ConsoleInstanceController.java#L123-L159","documentation":"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.","triggerScenarios":"Calling DELETE /v3/console/ns/instance with ephemeral=true (explicitly or because the form defaulted to true).","commonSituations":"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.","solutions":["Deregister ephemeral instances from the owning client/API rather than the console DELETE endpoint.","If you must use the console, target a persistent instance (ephemeral=false or null; buildInstance defaults null ephemeral to false).","Stop or reconfigure the registering client so it stops heartbeating, then the ephemeral instance expires on its own."],"exampleFix":"// before (ephemeral instance, rejected by console)\nform.setEphemeral(true);\ninstanceProxy.removeInstance(form, instance);\n\n// after (deregister via the owning client instead)\n// the client that registered the ephemeral instance should call:\nnamingService.deregisterInstance(serviceName, ip, port);\n// console DELETE only for persistent instances:\nform.setEphemeral(false);","handlingStrategy":"validation","validationCode":"// Do not deregister ephemeral instances via console DELETE\nBoolean ephemeral = instanceForm.getEphemeral();\nif (Boolean.TRUE.equals(ephemeral)) {\n    throw new UnsupportedOperationException(\n        \"Deregister ephemeral instances from the owning client, not the console\");\n}\ncontroller.removeInstance(instanceForm);","typeGuard":"// Java: guard that the instance is persistent before console deregister\nboolean consoleDeregisterable = !Boolean.TRUE.equals(instanceForm.getEphemeral());","tryCatchPattern":"try {\n    controller.removeInstance(form);\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()\n        && Boolean.TRUE.equals(form.getEphemeral())) {\n        // route deregistration to the owning client instead\n        namingService.deregisterInstance(svc, ip, port);\n    } else { throw e; }\n}","preventionTips":["Deregister ephemeral instances from the registering client, not the console.","Use the console DELETE only for persistent instances.","Set ephemeral=false (or leave null, which defaults to false) for console-managed instances."],"tags":["validation","naming","instance","ephemeral"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}