netty/netty · error · IllegalArgumentException

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

Error message

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

What it means

Thrown by DefaultHeaders.fromBoolean() when ValueConverter.convertBoolean(value) fails with IllegalArgumentException. This means the configured ValueConverter does not support boolean-to-V conversion. Most standard converters (CharSequenceValueConverter) handle this by converting to 'true'/'false' strings, but a custom or restricted ValueConverter might reject it.

Source

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

    @SuppressWarnings("unchecked")
    private T thisT() {
        return (T) this;
    }

    private V fromObject(K name, Object value) {
        try {
            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);
        }
    }

View on GitHub (pinned to 70040aacae)

Solutions

1. Ensure the ValueConverter implementation properly overrides convertBoolean() to return a valid V representation.
2. If the header expects a string, use headers.add(name, String.valueOf(boolValue)) instead of addBoolean().
3. Switch to a standard converter (CharSequenceValueConverter) if custom conversion is not needed.
4. Inspect the cause exception to see which constraint in convertBoolean() was violated.

Example fix

// before
headers.addBoolean("X-Enabled", true); // custom converter rejects boolean

// after — use string representation
headers.add("X-Enabled", String.valueOf(true));
// or fix the converter
public class MyConverter extends CharSequenceValueConverter {
    @Override public CharSequence convertBoolean(boolean v) { return v ? "1" : "0"; }
}

// Verify converter supports boolean before calling addBoolean
// For standard CharSequenceValueConverter, addBoolean always works.
// For custom converters, test convertBoolean:
ValueConverter<?> converter = headers.valueConverter();
try {
    converter.convertBoolean(true);
} catch (IllegalArgumentException test) {
    // converter doesn't support boolean — use string instead
    headers.add(name, String.valueOf(boolValue));
    return;
}
headers.addBoolean(name, boolValue);

static boolean converterSupportsBoolean(ValueConverter<?> converter) {
    try {
        converter.convertBoolean(true);
        converter.convertBoolean(false);
        return true;
    } catch (IllegalArgumentException e) {
        return false;
    }
}

try {
    headers.addBoolean(name, boolValue);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Failed to convert boolean value")) {
        // fall back to string representation
        headers.add(name, String.valueOf(boolValue));
    }
}

When it happens

Trigger: Calling headers.addBoolean(name, value) when the ValueConverter's convertBoolean() method throws IllegalArgumentException. This is rare with standard converters but occurs with custom ValueConverter implementations that don't implement or override convertBoolean(), or that impose additional validation on boolean representations.

Common situations: Using a custom ValueConverter that was only partially implemented (missing convertBoolean override); a converter that enforces a specific value format and rejects 'true'/'false' strings; header type systems where boolean values are not valid for certain header names; converter configured to use numeric (0/1) representation but receives a boolean.

Related errors

• Failed to convert object value for header '{name}'
• Failed to convert header value to boolean for header '<name>
• Failed to convert byte 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/5dbb51e61fd530b8. Report an issue: GitHub.