netty/netty · error · IllegalArgumentException

Validation failed for header '{name}'

Error message

Validation failed for header '{name}'

What it means

Thrown by DefaultHeaders.validateValue() when the configured ValueValidator rejects a header value with an IllegalArgumentException. Netty wraps the original exception and prefixes it with the header name for diagnostics. The ValueValidator is a pluggable component (defaults to a no-op validator) that can enforce constraints like charset, length, or format on header values.

Source

Thrown at codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java:1067

    }

    /**
     * Call out to the given {@link NameValidator} to validate the given name.
     *
     * @param validator the validator to use
     * @param forAdd {@code true } if this validation is for adding to the headers, or {@code false} if this is for
     * setting (overwriting) the given header.
     * @param name the name to validate.
     */
    protected void validateName(NameValidator<K> validator, boolean forAdd, K name) {
        validator.validateName(name);
    }

    protected void validateValue(ValueValidator<V> validator, K name, V value) {
        try {
            validator.validate(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Validation failed for header '" + name + "'", e);
        }
    }

    protected HeaderEntry<K, V> newHeaderEntry(int h, K name, V value, HeaderEntry<K, V> next) {
        return new HeaderEntry<K, V>(h, name, value, next, head);
    }

    protected ValueConverter<V> valueConverter() {
        return valueConverter;
    }

    protected NameValidator<K> nameValidator() {
        return nameValidator;
    }

    protected ValueValidator<V> valueValidator() {
        return valueValidator;
    }

View on GitHub (pinned to 70040aacae)

Solutions

1. Inspect the cause (getCause()) of the IllegalArgumentException to identify which validation rule failed.
2. Sanitize header values before adding: strip CRLF, validate charset, truncate length.
3. If the validator is too strict, replace it with a more permissive one or adjust its configuration.
4. Catch IllegalArgumentException at the header-setting call site and log/skip the offending header.

Example fix

// before
headers.add(name, rawValue); // fails validation

// after
String sanitized = rawValue.replaceAll("[\\r\\n]", "");
try {
    headers.add(name, sanitized);
} catch (IllegalArgumentException e) {
    log.warn("Rejected header {}: {}", name, e.getMessage());
}

// Validate value before adding to headers (if you know the validator rules)
String sanitized = value == null ? "" : value.replaceAll("[\\r\\n]", "");
if (sanitized.length() > maxLength) {
    sanitized = sanitized.substring(0, maxLength);
}
headers.add(name, sanitized);

try {
    headers.add(name, value);
} catch (IllegalArgumentException e) {
    // validation failed — inspect cause for which rule was violated
    log.warn("Header '{}' value rejected: {}", name, e.getCause().getMessage());
    // skip or sanitize the header
}

When it happens

Trigger: Adding or setting a header whose value fails the ValueValidator.validate() check. This occurs when a custom ValueValidator is installed (e.g., one that rejects non-ASCII characters, values exceeding a max length, or values containing CRLF injection characters) and the incoming value violates its rules.

Common situations: Installing a strict ValueValidator to prevent header injection and then receiving headers with special characters; proxying untrusted client headers through a validator that enforces charset restrictions; a validator that rejects null or empty values that a protocol legitimately sends; configuration drift where the validator is stricter than expected.

Related errors

• Can't parse more than 64 chars, looks like a user error or a
• can't add to itself.
• Failed to convert object value for header '{name}'
• Failed to convert boolean value for header '{name}'
• Failed to convert byte value for header '{name}'

AI-assisted analysis of netty/netty@70040aacae (2026-08-14). Data as JSON: /api/errors/ca0989314d0eed48. Report an issue: GitHub.