{"record":{"id":"1d39d42e13f39d64","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-value-s-s-to-byte","errorCode":null,"errorMessage":"Cannot coerce value '%s' [%s] to Byte","messagePattern":"Cannot coerce value '(.+?)' \\[(.+?)\\] to Byte","errorType":"exception","errorClass":"CoercionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/ByteJavaType.java","lineNumber":147,"sourceCode":"\n\t@Override\n\tpublic int getDefaultSqlPrecision(Dialect dialect, JdbcType jdbcType) {\n\t\treturn 3;\n\t}\n\n\t@Override\n\tpublic int getDefaultSqlScale(Dialect dialect, JdbcType jdbcType) {\n\t\treturn 0;\n\t}\n\n\t@Override\n\tpublic @Nullable Byte coerce(@Nullable Object value) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\tfinal var coerced = coerceOrNull( value );\n\t\tif ( coerced == null ) {\n\t\t\tthrow new CoercionException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Cannot coerce value '%s' [%s] to Byte\",\n\t\t\t\t\t\t\tvalue,\n\t\t\t\t\t\t\tvalue.getClass().getName()\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n\t\treturn coerced;\n\t}\n\n\t@Override\n\tpublic @Nullable Byte coerceOrNull(@Nonnull Object value) {\n\t\tif ( value instanceof Byte byteValue ) {\n\t\t\treturn byteValue;\n\t\t}\n\n\t\tif ( value instanceof Short shotValue ) {","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/ByteJavaType.java#L129-L165","documentation":"ByteJavaType.coerce supports Byte, Short, Integer, Long, Double, Float, BigInteger, BigDecimal and parseable numeric Strings. When coerceOrNull returns null — the value is some other type (Character, Boolean, LocalDate, ...) or a non-numeric string like '12a' — coerce throws CoercionException naming the value and its class. Note: out-of-range numbers do not produce this message; they raise the separate overflow/underflow CoercionExceptions from CoercionHelper.","triggerScenarios":"Binding an unsupported parameter type to a byte attribute — e.g. Character '7', Boolean, or String 'abc' — in HQL/Criteria or a dynamic parameter map; result-set coercion of a non-numeric column into a byte field.","commonSituations":"Loosely-typed parameter maps (Map<String,Object> queries); web/UI layers sending raw strings; schema drift where the column now holds non-numeric data.","solutions":["Convert the value to Byte (or a supported Number / numeric String) before binding.","Add an AttributeConverter matching the real source type.","Fix the query or parameter declaration so the bound type matches the byte attribute."],"exampleFix":"// before\nquery.setParameter(\"limit\", \"12a\"); // String not parseable -> CoercionException\n\n// after\nquery.setParameter(\"limit\", Byte.parseByte(valueFromUi)); // validate/parse up front","handlingStrategy":"type-guard","validationCode":"if (value instanceof String s && !s.matches(\"[+-]?\\d+\")) {\n    throw new IllegalArgumentException(\"Not a numeric value: \" + s);\n}","typeGuard":"static boolean isByteCoercible(Object v) {\n    return v == null || v instanceof Byte || v instanceof Short || v instanceof Integer\n        || v instanceof Long || v instanceof Double || v instanceof Float\n        || v instanceof BigInteger || v instanceof BigDecimal\n        || (v instanceof String s && s.matches(\"[+-]?\\\\d+\"));\n}","tryCatchPattern":null,"preventionTips":["Normalize parameter values to Byte/Number before query.setParameter.","Type your parameter maps; avoid Map<String,Object> for typed attributes.","Unit-test coercion paths with the exact runtime types you bind."],"tags":["hibernate","byte","coercion","type-mismatch"],"backgroundTag":"numeric-coercion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}