What causes "Cannot convert Character value '" + character + "' to Boolean" in hibernate/hibernate-orm?

Add an AttributeConverter that maps the actual stored characters ('T'/'F', '0'/'1') to Boolean.

hibernate/hibernate-orm · error · IllegalArgumentException

Cannot convert Character value '" + character + "' to Boolea

Error message

Cannot convert Character value '" + character + "' to Boolean

What it means

BooleanJavaType.wrap(value) accepts a Character only when it equals the configured true/false characters. With the default constructor those are 'Y'/'y' and 'N'/'n'; any other character ('T', 'F', '1', '0', 'X', ...) throws IllegalArgumentException because the value cannot be interpreted as a Boolean.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/BooleanJavaType.java:134

	@Override
	public <X> Boolean wrap(X value, WrapperOptions options) {
		if ( value == null ) {
			return null;
		}
		if (value instanceof Boolean booleanValue) {
			return booleanValue;
		}
		if (value instanceof Number number) {
			return number.intValue() != 0;
		}
		if (value instanceof Character character) {
			if ( isTrue( character ) ) {
				return true;
			}
			if ( isFalse( character ) ) {
				return false;
			}
			throw new IllegalArgumentException( "Cannot convert Character value '" + character + "' to Boolean" );
		}
		if (value instanceof String string) {
			if ( isTrue( string ) ) {
				return true;
			}
			if ( isFalse( string ) ) {
				return false;
			}
			throw new IllegalArgumentException( "Cannot convert value '" + string + "' to Boolean" );
		}
		throw unknownWrap( value.getClass() );
	}

	private boolean isTrue(String strValue) {
		return strValue != null
			&& !strValue.isEmpty()
			&& isTrue( strValue.charAt(0) );
	}

View on GitHub (pinned to fad1729dce)

Solutions

Add an AttributeConverter that maps the actual stored characters ('T'/'F', '0'/'1') to Boolean.
Migrate the column data to the 'Y'/'N' convention the descriptor expects.
Register a BooleanJavaType variant with the correct true/false characters (via a custom BasicType) if the whole schema uses a different encoding.
Bind real Boolean objects in queries instead of Characters.

Example fix

// before: column holds 'T'/'F'
@Basic private Boolean active; // wrap('T') -> IllegalArgumentException

// after
@Convert(converter = TfBooleanConverter.class)
private Boolean active;
...
public class TfBooleanConverter implements AttributeConverter<Boolean, Character> {
    public Character convertToDatabaseColumn(Boolean b) { return b ? 'T' : 'F'; }
    public Boolean convertToEntityAttribute(Character c) { return c == 'T'; }
}

Defensive patterns

Strategy: validation

Validate before calling

static boolean isBooleanChar(char c) {
    char u = Character.toUpperCase(c);
    return u == 'Y' || u == 'N'; // default BooleanJavaType convention
}

Type guard

static Boolean toBooleanOrNull(char c) {
    char u = Character.toUpperCase(c);
    if (u == 'Y') return Boolean.TRUE;
    if (u == 'N') return Boolean.FALSE;
    return null; // would throw in BooleanJavaType.wrap
}

Prevention

Store booleans as 'Y'/'N' or use a native boolean/integer column.
Add an AttributeConverter whenever the DB encoding differs from Y/N.
Bind Boolean parameters, never Character, in HQL/Criteria.

When it happens

Trigger: Binding a Character parameter to a boolean attribute in HQL/Criteria; a char(1) column storing T/F or 0/1 flags mapped straight to a Boolean field without a converter; data written under a different boolean character convention than the mapping expects.

Common situations: Porting a schema designed for another ORM that used 'T'/'F'; legacy databases with 0/1 character flags; switching dialect or boolean literal settings while old data keeps the previous encoding.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/14fdbf4287f4e7eb. Report an issue: GitHub.