alibaba/nacos · error · IllegalArgumentException

invalid groupkey:{groupKey}

Error message

invalid groupkey:{groupKey}

What it means

Thrown as IllegalArgumentException by GroupKey.parseKey() when the group key string contains more than two unescaped '+' delimiters. parseKey() splits on '+' into at most three parts (dataId, group, tenant). A third '+' means the key has a fourth segment, which is structurally invalid. This indicates the key string was constructed or corrupted incorrectly.

Source

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

     * @return parsed key
     */
    public static String[] parseKey(String groupKey) {
        StringBuilder sb = new StringBuilder();
        String dataId = null;
        String group = null;
        String tenant = null;
        
        for (int i = 0; i < groupKey.length(); ++i) {
            char c = groupKey.charAt(i);
            if (PLUS == c) {
                if (null == dataId) {
                    dataId = sb.toString();
                    sb.setLength(0);
                } else if (null == group) {
                    group = sb.toString();
                    sb.setLength(0);
                } else {
                    throw new IllegalArgumentException("invalid groupkey:" + groupKey);
                }
            } else if (PERCENT == c) {
                char next = groupKey.charAt(++i);
                char nextnext = groupKey.charAt(++i);
                if (TWO == next && B == nextnext) {
                    sb.append(PLUS);
                } else if (TWO == next && FIVE == nextnext) {
                    sb.append(PERCENT);
                } else {
                    throw new IllegalArgumentException("invalid groupkey:" + groupKey);
                }
            } else {
                sb.append(c);
            }
        }
        
        if (group == null) {
            group = sb.toString();

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Always use GroupKey.getKey() or getKeyTenant() to build keys — never manual string concatenation with '+'.
  2. If the key was built externally, URL-encode any '+' characters in dataId/group/tenant before assembling.
  3. Log the full groupKey value to identify which component contains the extra '+'.
  4. If parsing a key from an external/legacy source, validate its structure before calling parseKey().

Example fix

// before: manual concatenation can produce extra '+' delimiters
String key = dataId + "+" + group + "+" + tenant; // unsafe if values contain '+'
String[] parts = GroupKey.parseKey(key); // may throw

// after: always use GroupKey to build keys
String key = GroupKey.getKeyTenant(dataId, group, tenant); // encodes '+' as %2B
String[] parts = GroupKey.parseKey(key); // safe
Defensive patterns

Strategy: validation

Validate before calling

// Validate group key structure before parsing
// A valid key has at most 2 unescaped '+' delimiters
long plusCount = groupKey.chars().filter(c -> c == '+').count();
if (plusCount > 2) {
    throw new IllegalArgumentException("Group key has too many '+' separators: " + groupKey);
}
String[] parts = GroupKey.parseKey(groupKey);

Try / catch

try {
    String[] parts = GroupKey.parseKey(groupKey);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("invalid groupkey")) {
        log.error("Malformed group key '{}': too many '+' separators or unescaped characters",
            groupKey);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling GroupKey.parseKey() on a string that contains more than two literal '+' characters. This can happen if the key was assembled manually (not via getKey()), if a dataId/group/tenant contained an unescaped '+', or if the key string was truncated/concatenated incorrectly. The urlEncode() method escapes '+' as '%2B', so a raw '+' surviving into the key means encoding was bypassed.

Common situations: Manually building group key strings with string concatenation instead of GroupKey.getKey(). DataId, group, or tenant containing '+' that was not URL-encoded before being used in a key. Interoperability between systems that handle '+' differently. Corrupted or truncated cache keys.

Related errors

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