alibaba/nacos · error · IllegalArgumentException

Param 'serviceName' is illegal, it should be format as 'grou

Error message

Param 'serviceName' is illegal, it should be format as 'groupName@@serviceName'

What it means

checkServiceNameFormat validates a combined 'group@@name' string. If splitting on '@@' yields one or zero parts (no separator at all), the format is wrong and IllegalArgumentException is thrown.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/naming/utils/NamingUtils.java:136

        return !StringUtils.isBlank(serviceName)
            && serviceName.contains(Constants.SERVICE_INFO_SPLITER);
    }
    
    /**
     * check combineServiceName format. the serviceName can't be blank.
     * <pre>
     * serviceName = "@@";                 the length = 0; illegal
     * serviceName = "group@@";            the length = 1; illegal
     * serviceName = "@@serviceName";      the length = 2; illegal
     * serviceName = "group@@serviceName"; the length = 2; legal
     * </pre>
     *
     * @param combineServiceName such as: groupName@@serviceName
     */
    public static void checkServiceNameFormat(String combineServiceName) {
        String[] split = combineServiceName.split(Constants.SERVICE_INFO_SPLITER);
        if (split.length <= 1) {
            throw new IllegalArgumentException(
                "Param 'serviceName' is illegal, it should be format as 'groupName@@serviceName'");
        }
        if (split[0].isEmpty()) {
            throw new IllegalArgumentException(
                "Param 'serviceName' is illegal, groupName can't be empty");
        }
    }
    
    /**
     * Returns a combined string with serviceName and groupName. Such as 'groupName@@serviceName'
     * <p>This method works similar with {@link com.alibaba.nacos.api.naming.utils.NamingUtils#getGroupedName} But not
     * verify any parameters.
     *
     * </p> etc:
     * <p>serviceName | groupName | result</p>
     * <p>serviceA    | groupA    | groupA@@serviceA</p>
     * <p>nil         | groupA    | groupA@@</p>
     * <p>nil         | nil       | @@</p>

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass the combined 'group@@name' form.
2. Build the combined name with NamingUtils.getGroupedName(service, group) before calling APIs that require the combined form.

Example fix

// before
NamingUtils.checkServiceNameFormat("my-service");  // throws 544

// after
NamingUtils.checkServiceNameFormat("DEFAULT_GROUP@@my-service");

if (combineServiceName == null || !combineServiceName.contains(Constants.SERVICE_INFO_SPLITER)) {
    throw new IllegalArgumentException("expected 'group@@name' form");
}

When it happens

Trigger: Passing a bare serviceName ('my-service') where the API expects the combined form; unsubscribe/selectInstances with a non-grouped name.

Common situations: Mixing up serviceName and groupedServiceName across client APIs; older client behavior that auto-grouped now requiring explicit group.

Related errors

• Param 'serviceName' is illegal, groupName can't be empty
• Param 'serviceName' is illegal, serviceName is blank
• Param 'groupName' is illegal, groupName is blank
• illegal format, must be 'type:version', but got: {value}
• illegal version, must match: {UtilsAndCommons.VERSION_STRING

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