hibernate/hibernate-orm · error · CoercionException

value contains more than one character: '" + string + "'

Error message

value contains more than one character: '" + string + "'

What it means

CharacterJavaType.wrap throws CoercionException('value contains more than one character') when the incoming String is longer than one character — a Character attribute physically cannot hold more. This is the length>1 branch of the same switch that handles the empty-string case.

Source

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

		}
		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;
	}

	@Override
	public Class<Character[]> getArrayClass() {
		return Character[].class;

View on GitHub (pinned to fad1729dce)

Solutions

1. Fix the column to char(1) and clean existing data to single characters.
2. If truncation is intended, add a converter that explicitly takes the first character.
3. If the values are legitimately longer, change the attribute to String.

Example fix

-- before
ALTER TABLE users ALTER COLUMN initial TYPE varchar(3); -- values 'AB' appear
@Basic private Character initial; // wrap("AB") -> CoercionException

-- after
UPDATE users SET initial = SUBSTRING(initial FROM 1 FOR 1);
ALTER TABLE users ALTER COLUMN initial TYPE char(1);

static boolean fitsCharacter(String s) {
    return s == null || s.length() <= 1;
}
// reject or truncate explicitly: if (s.length() > 1) throw ...;

When it happens

Trigger: A varchar column with multi-character values feeding a Character attribute; native queries aliasing a wider column into a char(1) field; code setting a String into a Character property via the wrap path.

Common situations: Schema drift (column widened or reused for codes); joined lookup tables with 2-3 char codes; data entry that slipped past application validation.

Related errors

• Cannot convert Character value '" + character + "' to Boolea
• value must contain exactly one character: '" + string + "'
• The INSERT statement for table [%s] contains no column, and
• cannot recreate collection while filter is enabled: " + coll
• cannot recreate collection while filter is enabled [%s : %s]

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