{"record":{"id":"5dbb51e61fd530b8","repo":"netty/netty","slug":"failed-to-convert-boolean-value-for-header-name","errorCode":null,"errorMessage":"Failed to convert boolean value for header '{name}'","messagePattern":"Failed to convert boolean value for header '(.+?)'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java","lineNumber":1175,"sourceCode":"\n    @SuppressWarnings(\"unchecked\")\n    private T thisT() {\n        return (T) this;\n    }\n\n    private V fromObject(K name, Object value) {\n        try {\n            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    }","sourceCodeStart":1157,"sourceCodeEnd":1193,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/codec-base/src/main/java/io/netty/handler/codec/DefaultHeaders.java#L1157-L1193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the ValueConverter implementation properly overrides convertBoolean() to return a valid V representation.","If the header expects a string, use headers.add(name, String.valueOf(boolValue)) instead of addBoolean().","Switch to a standard converter (CharSequenceValueConverter) if custom conversion is not needed.","Inspect the cause exception to see which constraint in convertBoolean() was violated."],"exampleFix":"// before\nheaders.addBoolean(\"X-Enabled\", true); // custom converter rejects boolean\n\n// after — use string representation\nheaders.add(\"X-Enabled\", String.valueOf(true));\n// or fix the converter\npublic class MyConverter extends CharSequenceValueConverter {\n    @Override public CharSequence convertBoolean(boolean v) { return v ? \"1\" : \"0\"; }\n}","handlingStrategy":"type-guard","validationCode":"// Verify converter supports boolean before calling addBoolean\n// For standard CharSequenceValueConverter, addBoolean always works.\n// For custom converters, test convertBoolean:\nValueConverter<?> converter = headers.valueConverter();\ntry {\n    converter.convertBoolean(true);\n} catch (IllegalArgumentException test) {\n    // converter doesn't support boolean — use string instead\n    headers.add(name, String.valueOf(boolValue));\n    return;\n}\nheaders.addBoolean(name, boolValue);","typeGuard":"static boolean converterSupportsBoolean(ValueConverter<?> converter) {\n    try {\n        converter.convertBoolean(true);\n        converter.convertBoolean(false);\n        return true;\n    } catch (IllegalArgumentException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    headers.addBoolean(name, boolValue);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Failed to convert boolean value\")) {\n        // fall back to string representation\n        headers.add(name, String.valueOf(boolValue));\n    }\n}","preventionTips":["Ensure custom ValueConverter implementations override convertBoolean().","Prefer headers.add(name, String.valueOf(boolean)) if the converter is untrusted.","Use the standard CharSequenceValueConverter unless you have specific needs.","Unit test custom converters against all convertXxx methods."],"tags":["netty","codec","headers","type-conversion","value-converter","boolean"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}