alibaba/nacos · error · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

Unsupported request type %s

What it means

Thrown by PersistentInstanceRequestHandler.handle() when a persistent (non-ephemeral) instance gRPC request has a type other than REGISTER_INSTANCE or DE_REGISTER_INSTANCE. The switch covers only those two; anything else yields NacosException.INVALID_PARAM with the bad type. PersistentInstanceRequest targets persistent services (CP/RAFT), separate from the ephemeral InstanceRequest.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/remote/rpc/handler/PersistentInstanceRequestHandler.java:79

    @Override
    @NamespaceValidation
    @TpsControl(pointName = "RemoteNamingInstanceRegisterDeregister",
        name = "RemoteNamingInstanceRegisterDeregister")
    @Secured(action = ActionTypes.WRITE)
    @ExtractorManager.Extractor(rpcExtractor = PersistentInstanceRequestParamExtractor.class)
    public InstanceResponse handle(PersistentInstanceRequest request, RequestMeta meta)
        throws NacosException {
        Service service = Service.newService(request.getNamespace(), request.getGroupName(),
            request.getServiceName(),
            false);
        InstanceUtil.setInstanceIdIfEmpty(request.getInstance(), service.getGroupedServiceName());
        switch (request.getType()) {
            case NamingRemoteConstants.REGISTER_INSTANCE:
                return registerInstance(service, request, meta);
            case NamingRemoteConstants.DE_REGISTER_INSTANCE:
                return deregisterInstance(service, request, meta);
            default:
                throw new NacosException(NacosException.INVALID_PARAM,
                    String.format("Unsupported request type %s", request.getType()));
        }
    }
    
    private InstanceResponse registerInstance(Service service, PersistentInstanceRequest request,
        RequestMeta meta) {
        Instance instance = request.getInstance();
        String clientId = IpPortBasedClient.getClientId(instance.toInetAddr(), false);
        clientOperationService.registerInstance(service, instance, clientId);
        NotifyCenter.publishEvent(new RegisterInstanceTraceEvent(System.currentTimeMillis(),
            NamingRequestUtil.getSourceIpForGrpcRequest(meta), true, service.getNamespace(),
            service.getGroup(),
            service.getName(), instance.getIp(), instance.getPort()));
        return new InstanceResponse(NamingRemoteConstants.REGISTER_INSTANCE);
    }
    
    private InstanceResponse deregisterInstance(Service service, PersistentInstanceRequest request,
        RequestMeta meta) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set the type to REGISTER_INSTANCE or DE_REGISTER_INSTANCE.
2. Ensure the target service is persistent (ephemeral=false); use InstanceRequest for ephemeral services.
3. Align client and server Nacos versions.

Example fix

// before
PersistentInstanceRequest req = new PersistentInstanceRequest(ns, group, svc, "register", instance);
// after
PersistentInstanceRequest req = new PersistentInstanceRequest(ns, group, svc,
    NamingRemoteConstants.REGISTER_INSTANCE, instance);

String type = request.getType();
if (!NamingRemoteConstants.REGISTER_INSTANCE.equals(type)
    && !NamingRemoteConstants.DE_REGISTER_INSTANCE.equals(type)) {
    throw new IllegalArgumentException("Unsupported persistent instance request type: " + type);
}

static boolean isSupportedPersistentType(String type) {
    return NamingRemoteConstants.REGISTER_INSTANCE.equals(type)
        || NamingRemoteConstants.DE_REGISTER_INSTANCE.equals(type);
}

try {
    namingService.registerInstance(serviceName, instance);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
        && e.getMessage().contains("Unsupported request type")) {
        // ensure ephemeral vs persistent matches the service definition
    } else {
        throw e;
    }
}

When it happens

Trigger: Client sends a PersistentInstanceRequest whose type is not 'registerInstance' or 'deregisterInstance'.

Common situations: Using PersistentInstanceRequest where InstanceRequest was intended (ephemeral services); client/server version mismatch; a custom client passing the wrong type constant.

Related errors

• INVALID_PARAM
• INVALID_PARAM
• INVALID_PARAM
• INVALID_PARAM
• INVALID_PARAM

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