alibaba/nacos · error · IllegalArgumentException

invalid group

Error message

invalid group

What it means

Thrown as IllegalArgumentException by GroupKey.doGetKey() when the group parameter is null or blank (StringUtils.isBlank). doGetKey() is called by getKey() and getKeyTenant(). The group is a required component of the config composite key — a blank group makes the key ambiguous and is rejected.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/config/common/GroupKey.java:55

    
    public static String getKey(String dataId, String group) {
        return getKey(dataId, group, "");
    }
    
    public static String getKey(String dataId, String group, String datumStr) {
        return doGetKey(dataId, group, datumStr);
    }
    
    public static String getKeyTenant(String dataId, String group, String tenant) {
        return doGetKey(dataId, group, tenant);
    }
    
    private static String doGetKey(String dataId, String group, String datumStr) {
        if (StringUtils.isBlank(dataId)) {
            throw new IllegalArgumentException("invalid dataId");
        }
        if (StringUtils.isBlank(group)) {
            throw new IllegalArgumentException("invalid group");
        }
        StringBuilder sb = new StringBuilder();
        urlEncode(dataId, sb);
        sb.append(PLUS);
        urlEncode(group, sb);
        if (StringUtils.isNotEmpty(datumStr)) {
            sb.append(PLUS);
            urlEncode(datumStr, sb);
        }
        
        return sb.toString();
    }
    
    /**
     * Parse key.
     *
     * @param groupKey group key
     * @return parsed key

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Default group to Constants.DEFAULT_GROUP when the caller does not specify one, before calling GroupKey.getKey().
  2. Validate group is non-blank at the API boundary.
  3. Trace upstream to find where the null group originated.

Example fix

// before
String key = GroupKey.getKey(dataId, group); // throws if group is null

// after: apply default group
String resolvedGroup = StringUtils.isBlank(group) ? Constants.DEFAULT_GROUP : group;
String key = GroupKey.getKey(dataId, resolvedGroup);
Defensive patterns

Strategy: validation

Validate before calling

// Default group to DEFAULT_GROUP when not specified
String resolvedGroup = StringUtils.isBlank(group)
    ? Constants.DEFAULT_GROUP
    : group;
String key = GroupKey.getKey(dataId, resolvedGroup);

Try / catch

try {
    String key = GroupKey.getKey(dataId, group);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("invalid group")) {
        log.error("group is blank — apply Constants.DEFAULT_GROUP as fallback");
    }
    throw e;
}

Prevention

When it happens

Trigger: Any call to GroupKey.getKey() or GroupKey.getKeyTenant() with a null, empty, or whitespace-only group. Common in config operations where the developer omitted the group or passed an uninitialized variable. Note: Nacos uses Constants.DEFAULT_GROUP ("DEFAULT_GROUP") when group is not specified by the user, so hitting this means the default was not applied upstream.

Common situations: ConfigService calls where group was explicitly set to null instead of omitted (which would default to DEFAULT_GROUP). Internal code that extracts group from a parsed source that returned null. Config listener registration with a null group field.

Related errors

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