{"record":{"id":"ca0989314d0eed48","repo":"netty/netty","slug":"validation-failed-for-header-name","errorCode":null,"errorMessage":"Validation failed for header '{name}'","messagePattern":"Validation failed for header '(.+?)'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java","lineNumber":1067,"sourceCode":"    }\n\n    /**\n     * Call out to the given {@link NameValidator} to validate the given name.\n     *\n     * @param validator the validator to use\n     * @param forAdd {@code true } if this validation is for adding to the headers, or {@code false} if this is for\n     * setting (overwriting) the given header.\n     * @param name the name to validate.\n     */\n    protected void validateName(NameValidator<K> validator, boolean forAdd, K name) {\n        validator.validateName(name);\n    }\n\n    protected void validateValue(ValueValidator<V> validator, K name, V value) {\n        try {\n            validator.validate(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Validation failed for header '\" + name + \"'\", e);\n        }\n    }\n\n    protected HeaderEntry<K, V> newHeaderEntry(int h, K name, V value, HeaderEntry<K, V> next) {\n        return new HeaderEntry<K, V>(h, name, value, next, head);\n    }\n\n    protected ValueConverter<V> valueConverter() {\n        return valueConverter;\n    }\n\n    protected NameValidator<K> nameValidator() {\n        return nameValidator;\n    }\n\n    protected ValueValidator<V> valueValidator() {\n        return valueValidator;\n    }","sourceCodeStart":1049,"sourceCodeEnd":1085,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java#L1049-L1085","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause (getCause()) of the IllegalArgumentException to identify which validation rule failed.","Sanitize header values before adding: strip CRLF, validate charset, truncate length.","If the validator is too strict, replace it with a more permissive one or adjust its configuration.","Catch IllegalArgumentException at the header-setting call site and log/skip the offending header."],"exampleFix":"// before\nheaders.add(name, rawValue); // fails validation\n\n// after\nString sanitized = rawValue.replaceAll(\"[\\\\r\\\\n]\", \"\");\ntry {\n    headers.add(name, sanitized);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Rejected header {}: {}\", name, e.getMessage());\n}","handlingStrategy":"try-catch","validationCode":"// Validate value before adding to headers (if you know the validator rules)\nString sanitized = value == null ? \"\" : value.replaceAll(\"[\\\\r\\\\n]\", \"\");\nif (sanitized.length() > maxLength) {\n    sanitized = sanitized.substring(0, maxLength);\n}\nheaders.add(name, sanitized);","typeGuard":null,"tryCatchPattern":"try {\n    headers.add(name, value);\n} catch (IllegalArgumentException e) {\n    // validation failed — inspect cause for which rule was violated\n    log.warn(\"Header '{}' value rejected: {}\", name, e.getCause().getMessage());\n    // skip or sanitize the header\n}","preventionTips":["Sanitize header values at the trust boundary: strip CRLF, validate charset, cap length.","Understand which ValueValidator is configured and its constraints.","Inspect getCause() to diagnose which validation rule rejected the value.","Catch IllegalArgumentException at the header-setting boundary for untrusted input."],"tags":["netty","codec","headers","validation","header-injection"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}