netty/netty · error · IllegalArgumentException

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

Error message

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

What it means

DefaultHeaders turns a Java `long` into value type V via ValueConverter.convertLong; an IllegalArgumentException from the converter is rewrapped with the header name. The default converter calls Long.toString and cannot fail, so the throw comes from a custom converter.

Source

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

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

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

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

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

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

View on GitHub (pinned to 70040aacae)

Solutions

1. Inspect the ValueConverter used by DefaultHeaders and read convertLong's rule.
2. Validate the long against that rule before addLong/setLong.
3. Use the default CharSequenceValueConverter if you do not need custom long handling.

Example fix

// before
headers.setLong("size", size);

// after: enforce the converter's rule
if (size < 0) {
    throw new IllegalArgumentException("size must be >= 0");
}
headers.setLong("size", size);

// Validate the long against your converter's rule (e.g. non-negative size).
long size = ...;
if (size < 0) {
    throw new IllegalArgumentException("size must be >= 0");
}
headers.setLong("size", size);

When it happens

Trigger: Calling headers.addLong(name, l), headers.setLong(name, l), or addObject/setObject with a long on a DefaultHeaders whose ValueConverter.convertLong throws.

Common situations: A custom converter rejecting negative longs (e.g. sizes, timestamps); a converter enforcing max values; a misbehaving converter.

Related errors

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

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