netty/netty · error · IllegalArgumentException

Failed to convert byte value for header '{name}'

Error message

Failed to convert byte value for header '{name}'

What it means

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.

Source

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

            return valueConverter.convertObject(checkNotNull(value, "value"));
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Failed to convert object value for header '" + name + '\'', e);
        }
    }

    private V fromBoolean(K name, boolean value) {
        try {
            return valueConverter.convertBoolean(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Failed to convert boolean value for header '" + name + '\'', e);
        }
    }

    private V fromByte(K name, byte value) {
        try {
            return valueConverter.convertByte(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Failed to convert byte value for header '" + name + '\'', e);
        }
    }

    private V fromChar(K name, char value) {
        try {
            return valueConverter.convertChar(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Failed to convert char value for header '" + name + '\'', e);
        }
    }

    private V fromShort(K name, short value) {
        try {
            return valueConverter.convertShort(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Failed to convert short value for header '" + name + '\'', e);
        }
    }

View on GitHub (pinned to 70040aacae)

Solutions

1. Open the ValueConverter implementation passed into DefaultHeaders (or the Netty headers subtype) and read convertByte's contract to see why it rejects.
2. If the restriction is intentional, validate the byte against that rule before calling addByte/setByte.
3. If no special conversion is needed, use the default CharSequenceValueConverter so byte-to-String conversion cannot fail.

Example fix

// before: custom converter throws for out-of-range bytes
headers.setByte("retry-flag", value);

// after: gate on the converter's own accepted range
if (value < 0 || value > 1) {
    throw new IllegalArgumentException("retry-flag must be 0 or 1");
}
headers.setByte("retry-flag", value);

// Validate the byte against your ValueConverter's accepted rule BEFORE setByte.
// Example: converter only accepts 0/1 flags.
byte value = ...;
if (value < 0 || value > 1) {
    throw new IllegalArgumentException("flag must be 0 or 1, got " + value);
}
headers.setByte("flag", value);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to convert header value to byte for header '<name>'
• Failed to convert object value for header '{name}'
• Failed to convert boolean value for header '{name}'
• Failed to convert char value for header '{name}'
• Failed to convert short value for header '{name}'

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