{"record":{"id":"5e950a1fa7fdc4ea","repo":"netty/netty","slug":"failed-to-convert-byte-value-for-header-name","errorCode":null,"errorMessage":"Failed to convert byte value for header '{name}'","messagePattern":"Failed to convert byte value for header '(.+?)'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java","lineNumber":1183,"sourceCode":"            return valueConverter.convertObject(checkNotNull(value, \"value\"));\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Failed to convert object value for header '\" + name + '\\'', e);\n        }\n    }\n\n    private V fromBoolean(K name, boolean value) {\n        try {\n            return valueConverter.convertBoolean(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Failed to convert boolean value for header '\" + name + '\\'', e);\n        }\n    }\n\n    private V fromByte(K name, byte value) {\n        try {\n            return valueConverter.convertByte(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Failed to convert byte value for header '\" + name + '\\'', e);\n        }\n    }\n\n    private V fromChar(K name, char value) {\n        try {\n            return valueConverter.convertChar(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Failed to convert char value for header '\" + name + '\\'', e);\n        }\n    }\n\n    private V fromShort(K name, short value) {\n        try {\n            return valueConverter.convertShort(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Failed to convert short value for header '\" + name + '\\'', e);\n        }\n    }","sourceCodeStart":1165,"sourceCodeEnd":1201,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java#L1165-L1201","documentation":"DefaultHeaders stores header values as type V (usually a String/CharSequence). Before adding a Java `byte`, it runs it through the configured ValueConverter.convertByte; if the converter rejects the value with an IllegalArgumentException, this message is rethrown with the offending header name attached. The stock CharSequenceValueConverter never throws here, so in practice this almost always means a custom converter is enforcing an extra rule or has a bug.","triggerScenarios":"Calling headers.addByte(name, value), headers.setByte(name, value), or addObject/setObject with a byte on a DefaultHeaders (or an HTTP/HTTP2 headers subtype) whose ValueConverter.convertByte throws IllegalArgumentException.","commonSituations":"A custom ValueConverter that restricts the accepted byte range (e.g. flags must be 0/1); a converter reused across header kinds with incompatible rules; a converter bug that throws on otherwise-valid input.","solutions":["Open the ValueConverter implementation passed into DefaultHeaders (or the Netty headers subtype) and read convertByte's contract to see why it rejects.","If the restriction is intentional, validate the byte against that rule before calling addByte/setByte.","If no special conversion is needed, use the default CharSequenceValueConverter so byte-to-String conversion cannot fail."],"exampleFix":"// before: custom converter throws for out-of-range bytes\nheaders.setByte(\"retry-flag\", value);\n\n// after: gate on the converter's own accepted range\nif (value < 0 || value > 1) {\n    throw new IllegalArgumentException(\"retry-flag must be 0 or 1\");\n}\nheaders.setByte(\"retry-flag\", value);","handlingStrategy":"validation","validationCode":"// Validate the byte against your ValueConverter's accepted rule BEFORE setByte.\n// Example: converter only accepts 0/1 flags.\nbyte value = ...;\nif (value < 0 || value > 1) {\n    throw new IllegalArgumentException(\"flag must be 0 or 1, got \" + value);\n}\nheaders.setByte(\"flag\", value);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Know your ValueConverter's contract before calling addByte/setByte; the default converter never throws, custom ones may.","Centralize byte-to-header writes behind a helper that validates the domain rule, so callers cannot bypass it.","Unit-test the converter's convertByte against boundary values once, instead of relying on runtime exceptions."],"tags":["netty","codec","headers","value-converter","byte"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}