quarkusio/quarkus · error · IllegalArgumentException

Cannot add header, key and value must not be null

Error message

Cannot add header, key and value must not be null

What it means

Mail.addHeader(key, values...) validates its arguments and throws IllegalArgumentException when the header name or the values array itself is null. Individual null entries inside the values array are allowed and stored as-is; the guard is only against a null name or a null array.

Source

Thrown at extensions/mailer/runtime/src/main/java/io/quarkus/mailer/Mail.java:318

    }

    /**
     * @return the current set of headers.
     */
    public Map<String, List<String>> getHeaders() {
        return headers;
    }

    /**
     * Adds a header value. If this header already has a value, the value is appended.
     *
     * @param key the header name, must not be {@code null}
     * @param values the header values, must not be {@code null}
     * @return the current {@link Mail}
     */
    public Mail addHeader(String key, String... values) {
        if (key == null || values == null) {
            throw new IllegalArgumentException("Cannot add header, key and value must not be null");
        }
        List<String> content = this.headers.computeIfAbsent(key, k -> new ArrayList<>());
        Collections.addAll(content, values);
        return this;
    }

    /**
     * Removes a header.
     *
     * @param key the header name, must not be {@code null}.
     * @return the current {@link Mail}
     */
    public Mail removeHeader(String key) {
        if (key == null) {
            throw new IllegalArgumentException("Cannot remove header, key must not be null");
        }
        headers.remove(key);
        return this;

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the header name is non-null before calling addHeader (check map/config lookup results)
2. Pass an empty array or skip the call when there are no values, instead of passing null
3. Validate upstream data that produces the header name

Example fix

// before
String name = headerMap.get("Reply-To");
mail.addHeader(name, value); // NPE risk -> IAE when name==null
// after
if (name != null && value != null) {
    mail.addHeader(name, value);
}

if (key == null || values == null) {
    throw new IllegalArgumentException("header name and values must not be null");
}
mail.addHeader(key, values);

boolean isAddableHeader(String key, String... values) {
    return key != null && values != null;
}

try {
    mail.addHeader(key, values);
} catch (IllegalArgumentException e) {
    log.warnf("Skipped mail header: %s", e.getMessage());
}

When it happens

Trigger: Calling mail.addHeader(null, "v") or mail.addHeader("X-Custom", (String[]) null) — typically when the header name/value comes from a variable or map lookup that returned null.

Common situations: Building headers from a Map<String,String> where a key/value is absent; dynamic header names from config or request data; null returned by a helper producing the header name.

Related errors

• Cannot remove header, key must not be null
• An attachment must contain either a file or a raw data
• name cannot be null
• Either location or predicate must be set
• At least one package name must be specified

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/0a8f04f7b39c1d33. Report an issue: GitHub.