alibaba/nacos · error · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

Param 'serviceName' is illegal, serviceName is blank

What it means

Thrown by SubscribeServiceRequestHandler.handle() when a subscribe/unsubscribe gRPC request has a blank serviceName. The handler needs the service to subscribe to; a blank serviceName yields NacosException.INVALID_PARAM. Note this handler also enforces namespace via @NamespaceValidation before reaching this code.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/remote/rpc/handler/SubscribeServiceRequestHandler.java:85

        EphemeralClientOperationServiceImpl clientOperationService) {
        this.serviceStorage = serviceStorage;
        this.metadataManager = metadataManager;
        this.clientOperationService = clientOperationService;
    }
    
    @Override
    @NamespaceValidation
    @TpsControl(pointName = "RemoteNamingServiceSubscribeUnSubscribe",
        name = "RemoteNamingServiceSubscribeUnsubscribe")
    @Secured(action = ActionTypes.READ)
    @ExtractorManager.Extractor(rpcExtractor = SubscribeServiceRequestParamExtractor.class)
    public SubscribeServiceResponse handle(SubscribeServiceRequest request, RequestMeta meta)
        throws NacosException {
        String namespaceId = request.getNamespace();
        String serviceName = request.getServiceName();
        String groupName = request.getGroupName();
        if (StringUtils.isBlank(serviceName)) {
            throw new NacosException(NacosException.INVALID_PARAM,
                "Param 'serviceName' is illegal, serviceName is blank");
        }
        if (StringUtils.isBlank(groupName)) {
            throw new NacosException(NacosException.INVALID_PARAM,
                "Param 'groupName' is illegal, groupName is blank");
        }
        String app = RequestContextHolder.getContext().getBasicContext().getApp();
        String groupedServiceName = NamingUtils.getGroupedName(serviceName, groupName);
        Service service = Service.newService(namespaceId, groupName, serviceName, true);
        Subscriber subscriber =
            new Subscriber(meta.getClientIp(), meta.getClientVersion(), app, meta.getClientIp(),
                namespaceId, groupedServiceName, 0, request.getClusters());
        ServiceInfo serviceInfo =
            ServiceUtil.selectInstancesWithHealthyProtection(serviceStorage.getData(service),
                metadataManager.getServiceMetadata(service).orElse(null), subscriber.getCluster(),
                false, true,
                subscriber.getIp());
        if (request.isSubscribe()) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Set a non-blank serviceName on the SubscribeServiceRequest.
Use the NamingService.subscribe(serviceName, ...) API which requires the name up front.
For pattern-based watching, use the fuzzy-watch API instead of subscribe with a blank name.

Example fix

// before
SubscribeServiceRequest req = new SubscribeServiceRequest(ns, group, "", clusters, false);
// after
SubscribeServiceRequest req = new SubscribeServiceRequest(ns, group, "my-service", clusters, false);

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(request.getServiceName())) {
    throw new IllegalArgumentException("serviceName is required to subscribe");
}

Type guard

static boolean hasServiceName(SubscribeServiceRequest r) {
    return r != null && StringUtils.isNotBlank(r.getServiceName());
}

Try / catch

try {
    namingService.subscribe(serviceName, listener);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
        && e.getMessage().contains("serviceName is blank")) {
        // supply the service name and retry
    } else {
        throw e;
    }
}

Prevention

Resolve serviceName before subscribing; do not subscribe with a blank name.
Use the high-level NamingService.subscribe API.
For pattern-based watching, use fuzzy-watch instead.

When it happens

Trigger: Client sends a SubscribeServiceRequest with an empty/null serviceName (groupName may be set).

Common situations: SDK subscribe call before serviceName is known; a watch-all misuse that passes an empty pattern; building the request from a null service object.

Related errors

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