{"record":{"id":"a5246bc06b9bbb91","repo":"hibernate/hibernate-orm","slug":"value-does-not-contain-a-character-string","errorCode":null,"errorMessage":"value does not contain a character: '\" + string + \"'","messagePattern":"value does not contain a character: '\" \\+ string \\+ \"'","errorType":"exception","errorClass":"CoercionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CharacterJavaType.java","lineNumber":89,"sourceCode":"\tpublic <X> Character wrap(X value, WrapperOptions options) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\telse if (value instanceof Character character) {\n\t\t\treturn character;\n\t\t}\n\t\telse if (value instanceof String string) {\n\t\t\tswitch ( string.length() ) {\n\t\t\t\tcase 1:\n\t\t\t\t\treturn string.charAt( 0 );\n\t\t\t\tcase 0:\n\t\t\t\t\tif ( options.getDialect().stripsTrailingSpacesFromChar() ) {\n\t\t\t\t\t\t// we previously stored char values in char(1) columns on MySQL\n\t\t\t\t\t\t// but MySQL strips trailing spaces from the value when read\n\t\t\t\t\t\treturn ' ';\n\t\t\t\t\t}\n\t\t\t\t\telse {\n\t\t\t\t\t\tthrow new CoercionException( \"value does not contain a character: '\" + string + \"'\" );\n\t\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\tthrow new CoercionException( \"value contains more than one character: '\" + string + \"'\" );\n\t\t\t}\n\t\t}\n\t\telse if (value instanceof Number number) {\n\t\t\treturn (char) number.shortValue();\n\t\t}\n\t\telse {\n\t\t\tthrow unknownWrap( value.getClass() );\n\t\t}\n\t}\n\n\t@Override\n\tpublic Class<?> getPrimitiveClass() {\n\t\treturn char.class;\n\t}\n","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CharacterJavaType.java#L71-L107","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (PostgreSQL, char(1) column containing '')\n@Basic private Character initial; // wrap(\"\") -> CoercionException\n\n-- data fix\nUPDATE users SET initial = ' ' WHERE initial = '';\n\n// or converter\npublic Character convertToEntityAttribute(String s) { return (s == null || s.isEmpty()) ? ' ' : s.charAt(0); }","handlingStrategy":"validation","validationCode":"// before persisting or mapping onto a Character attribute\nif (value != null && value.isEmpty()) {\n    value = \" \"; // or reject: your dialect will not map '' to ' '\n}","typeGuard":"static boolean isCharBindable(String s) {\n    return s == null || s.length() == 1; // '' is unsafe on non-MySQL dialects\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["hibernate","character","empty-string","dialect","mysql-migration"],"backgroundTag":"character-length-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}