quarkusio/quarkus · error · IllegalArgumentException

Cannot remove header, key must not be null

Error message

Cannot remove header, key must not be null

What it means

Mail.removeHeader(key) rejects a null header name with IllegalArgumentException. It is a public API guard; the method then simply removes the (possibly absent) key from the headers map, so a non-null key that does not exist is not an error.

Source

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

     */
    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;
    }

    /**
     * Sets the list of headers.
     *
     * @param headers the headers
     * @return the current {@link Mail}
     */
    public Mail setHeaders(Map<String, List<String>> headers) {
        this.headers = Objects.requireNonNullElseGet(headers, HashMap::new);
        return this;
    }

    /**
     * Adds an inline attachment.

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the header name for null before calling removeHeader
2. Skip the call when the name is null/blank
3. Ensure the source of the header name (config, map, request attribute) is populated

Example fix

// before
mail.removeHeader(configuredHeaderName); // null when not configured
// after
if (configuredHeaderName != null) {
    mail.removeHeader(configuredHeaderName);
}

if (key != null) {
    mail.removeHeader(key);
}

boolean isRemovableHeader(String key) {
    return key != null && !key.isBlank();
}

try {
    mail.removeHeader(key);
} catch (IllegalArgumentException e) {
    log.warnf("Ignoring null header name on remove");
}

When it happens

Trigger: Calling mail.removeHeader(null), usually because the header name came from a variable, map lookup, or optional field that was null.

Common situations: Removing a conditional header based on user input or configuration where the name resolves to null; generic header-manipulation helper methods that don't pre-check names.

Related errors

• Cannot add header, key and value 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/638700c27d67a6dd. Report an issue: GitHub.