alibaba/Sentinel · warning · IllegalArgumentException

Metadata key cannot be empty

Error message

Metadata key cannot be empty

What it means

CommandRequest.addMetadata rejects blank metadata keys with IllegalArgumentException, mirroring addParam. Metadata carries per-request transport info (e.g. the "command-target" entry used by HttpCommandUtils.getTarget to route a request to its handler), so a blank key would corrupt routing. It is populated by command-center request parsers (netty HttpServerHandler, simple-http HttpEventTask).

Source

Thrown at sentinel-transport/sentinel-transport-common/src/main/java/com/alibaba/csp/sentinel/command/CommandRequest.java:70

        String value = parameters.get(key);
        return StringUtil.isBlank(value) ? defaultValue : value;
    }

    public CommandRequest addParam(String key, String value) {
        if (StringUtil.isBlank(key)) {
            throw new IllegalArgumentException("Parameter key cannot be empty");
        }
        parameters.put(key, value);
        return this;
    }

    public Map<String, String> getMetadata() {
        return metadata;
    }

    public CommandRequest addMetadata(String key, String value) {
        if (StringUtil.isBlank(key)) {
            throw new IllegalArgumentException("Metadata key cannot be empty");
        }
        metadata.put(key, value);
        return this;
    }
}

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Skip blank keys when copying headers: filter with StringUtil.isNotBlank before addMetadata
2. Fix the header-parsing code that produced an empty name (usually a wrong indexOf(":") split)
3. Only add well-known metadata keys (e.g. HttpCommandUtils.REQUEST_TARGET) in custom transports

Example fix

// before
for (String k : headers.keySet()) {
    request.addMetadata(k, headers.get(k));
}

// after
for (Map.Entry<String,String> e : headers.entrySet()) {
    if (StringUtil.isNotBlank(e.getKey())) {
        request.addMetadata(e.getKey(), e.getValue());
    }
}

if (StringUtil.isNotBlank(key)) {
    request.addMetadata(key, value);
}

When it happens

Trigger: request.addMetadata("", value) or addMetadata(null, value); most often from custom code copying external header maps into metadata where a header line like ": value" yields an empty key.

Common situations: Forwarding arbitrary HTTP headers into CommandRequest metadata without filtering; parsing bugs in custom transports that split headers on the wrong delimiter; test fixtures with empty header names.

Related errors

• Parameter key cannot be empty
• Parameter key cannot be empty
• maxSize must > 0
• Bad byte array
• Only form-encoded post request is supported

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/b46dac282567a542. Report an issue: GitHub.