{"record":{"id":"7a86f818435d4a86","repo":"hibernate/hibernate-orm","slug":"the-string-is-not-a-valid-string-representation-of-7a86f8","errorCode":null,"errorMessage":"The string is not a valid string representation of a binary content.","messagePattern":"The string is not a valid string representation of a binary content\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/PrimitiveByteArrayJavaType.java","lineNumber":99,"sourceCode":"\t\t\tif ( hexStr.length() == 1 ) {\n\t\t\t\tappender.append( '0' );\n\t\t\t}\n\t\t\tappender.append( hexStr );\n\t\t}\n\t}\n\n\t@Override\n\tpublic String extractLoggableRepresentation(byte[] value) {\n\t\treturn value == null ? super.extractLoggableRepresentation( null ) : Arrays.toString( value );\n\t}\n\n\t@Override\n\tpublic byte[] fromString(CharSequence string) {\n\t\tif ( string == null ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( string.length() % 2 != 0 ) {\n\t\t\tthrow new IllegalArgumentException( \"The string is not a valid string representation of a binary content.\" );\n\t\t}\n\t\tbyte[] bytes = new byte[string.length() / 2];\n\t\tfor ( int i = 0; i < bytes.length; i++ ) {\n\t\t\tfinal String hexStr = string.subSequence( i * 2, (i + 1) * 2 ).toString();\n\t\t\tbytes[i] = (byte) Integer.parseInt( hexStr, 16 );\n\t\t}\n\t\treturn bytes;\n\t}\n\n\tpublic <X> X unwrap(byte[] value, Class<X> type, WrapperOptions options) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( byte[].class.isAssignableFrom( type ) ) {\n\t\t\treturn type.cast( value );\n\t\t}\n\t\tif ( InputStream.class.isAssignableFrom( type ) ) {\n\t\t\treturn type.cast( new ByteArrayInputStream( value ) );","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/PrimitiveByteArrayJavaType.java#L81-L117","documentation":"PrimitiveByteArrayJavaType.fromString() decodes byte[] from hexadecimal text and requires an even number of characters (two hex digits per byte). Any odd-length string - truncated hex, a stray nibble, values with partial '0x'-style prefixes - is rejected with IllegalArgumentException before parsing starts. This path is used when binary values are materialized from text, e.g. varchar columns on databases lacking a binary type.","triggerScenarios":"A byte[] attribute backed by a text column whose content has odd length (truncated by ETL or hand editing); hex strings with an odd nibble like '0AF'; another writer storing base64 or '0x'-prefixed hex that left a stray character","commonSituations":"Storing binary as hex on databases without VARBINARY/BLOB support; data cleanup jobs that trimmed characters; integrations that concatenate hex strings incorrectly","solutions":["Fix the data: hex must have even length; re-export or repair truncated values","Use a real binary column type (VARBINARY, BLOB, RAW) so no hex round-trip occurs","Validate length % 2 == 0 (and [0-9a-fA-F] only) at every write path before persisting","If base64 or prefixed hex is the real format, use an AttributeConverter that decodes it properly"],"exampleFix":"// before\nUPDATE files SET hash_hex = '0AF'; // odd length\n// loading byte[] attribute -> IllegalArgumentException\n\n// after\nUPDATE files SET hash_hex = '00AF';\n// plus a write-side guard: if (hex.length() % 2 != 0) throw ...","handlingStrategy":"validation","validationCode":"static boolean isValidHex(byte[] target, CharSequence s) {\n    return s != null && s.length() % 2 == 0 && s.chars().allMatch(c -> Character.digit(c, 16) >= 0);\n}\n\nif (!isValidHex(null, text)) throw new IllegalArgumentException(\"Even-length hex string required: \" + text);","typeGuard":"static byte[] tryHexDecode(String s) {\n    if (s == null || s.length() % 2 != 0) return null;\n    try { return java.util.HexFormat.of().parseHex(s); } catch (Exception e) { return null; }\n}","tryCatchPattern":"catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"binary content\"))\n        throw new IllegalArgumentException(\"Hex text must have even length: '\" + text + \"'\", e);\n    throw e;\n}","preventionTips":["Enforce even-length, [0-9a-f] hex at every write boundary","Use native binary columns (VARBINARY/BLOB/RAW) instead of hex text","Add a checksum/length column to detect truncated hex imports"],"tags":["hibernate","byte-array","hex-decoding","binary-column","data-corruption"],"backgroundTag":"hex-binary-decode-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}