alibaba/nacos · error · IllegalArgumentException

Param 'serviceName' is illegal, groupName can't be empty

Error message

Param 'serviceName' is illegal, groupName can't be empty

What it means

Second guard inside checkServiceNameFormat: even when '@@' is present, the groupName segment (split[0]) must not be empty. This rejects inputs like '@@serviceName' that look formatted but are missing the group.

Source

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

    /**
     * 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>
     *
     * @return 'groupName@@serviceName'
     */
    public static String getGroupedNameOptional(final String serviceName, final String groupName) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure a non-empty group segment before the '@@'.
Construct the combined name via NamingUtils.getGroupedName so groupName is validated first.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

if (combineServiceName == null || combineServiceName.isEmpty()
        || combineServiceName.startsWith(Constants.SERVICE_INFO_SPLITER)) {
    throw new IllegalArgumentException("group segment must not be empty");
}

Prevention

Never concatenate '@@' with a null/blank left-hand variable.
Unit-test key builders with blank group inputs.

When it happens

Trigger: checkServiceNameFormat("@@my-service"); a corrupted key where the group prefix was stripped.

Common situations: String manipulation that trimmed the group; concatenated key with a null/blank group variable on the left of '@@'.

Related errors

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