What causes "value does not contain a character: '" + string + "'" in hibernate/hibernate-orm?

Store a real character or make the column nullable with a NULL default.

hibernate/hibernate-orm · error · CoercionException

value does not contain a character: '" + string + "'

Error message

value does not contain a character: '" + string + "'

What it means

In CharacterJavaType.wrap, an empty string is tolerated only when the dialect strips trailing spaces from char columns (stripsTrailingSpacesFromChar(), the MySQL family): an all-space char(1) value read back as '' is then mapped to ' '. On any other dialect an empty string throws CoercionException('value does not contain a character').

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CharacterJavaType.java:89

	public <X> Character wrap(X value, WrapperOptions options) {
		if ( value == null ) {
			return null;
		}
		else if (value instanceof Character character) {
			return character;
		}
		else if (value instanceof String string) {
			switch ( string.length() ) {
				case 1:
					return string.charAt( 0 );
				case 0:
					if ( options.getDialect().stripsTrailingSpacesFromChar() ) {
						// we previously stored char values in char(1) columns on MySQL
						// but MySQL strips trailing spaces from the value when read
						return ' ';
					}
					else {
						throw new CoercionException( "value does not contain a character: '" + string + "'" );
					}
				default:
					throw new CoercionException( "value contains more than one character: '" + string + "'" );
			}
		}
		else if (value instanceof Number number) {
			return (char) number.shortValue();
		}
		else {
			throw unknownWrap( value.getClass() );
		}
	}

	@Override
	public Class<?> getPrimitiveClass() {
		return char.class;
	}

View on GitHub (pinned to fad1729dce)

Solutions

Store a real character or make the column nullable with a NULL default.
Add an AttributeConverter that maps '' to a default character (e.g., ' ').
Verify what the dialect actually returns for padded values and align the data with it.

Example fix

// before (PostgreSQL, char(1) column containing '')
@Basic private Character initial; // wrap("") -> CoercionException

-- data fix
UPDATE users SET initial = ' ' WHERE initial = '';

// or converter
public Character convertToEntityAttribute(String s) { return (s == null || s.isEmpty()) ? ' ' : s.charAt(0); }

Defensive patterns

Strategy: validation

Validate before calling

// before persisting or mapping onto a Character attribute
if (value != null && value.isEmpty()) {
    value = " "; // or reject: your dialect will not map '' to ' '
}

Type guard

static boolean isCharBindable(String s) {
    return s == null || s.length() == 1; // '' is unsafe on non-MySQL dialects
}

Prevention

Never insert '' into columns backing Character attributes.
Default NOT NULL char columns to a space or make them nullable.
After MySQL-to-other-DB migrations, sweep char columns for empty strings.

When it happens

Trigger: A char(1) column containing '' (or a space-only value read as empty) on PostgreSQL, H2, SQL Server, Oracle, etc.; inserting '' as the default for a NOT NULL Character attribute.

Common situations: Migrating a MySQL application (where trailing spaces are stripped and '' meant a space) to another database; NOT NULL char(1) columns defaulted to empty string; web forms submitting empty values that get persisted.

Related errors

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