{"record":{"id":"42dcb4269933c264","repo":"hibernate/hibernate-orm","slug":"couldn-t-interpret-s-as-jdbc-type-code-or-type","errorCode":null,"errorMessage":"Couldn't interpret '%s' as JDBC type code or type code name","messagePattern":"Couldn't interpret '(.+?)' as JDBC type code or type code name","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java","lineNumber":494,"sourceCode":"\t\tpublic static final TypeCodeConverter INSTANCE = new TypeCodeConverter();\n\n\t\t@Override\n\t\t@Nonnull\n\t\tpublic Integer convert(@Nonnull Object value) {\n\t\t\tif ( value instanceof Number number ) {\n\t\t\t\treturn number.intValue();\n\t\t\t}\n\n\t\t\tfinal String string = value.toString().toUpperCase( Locale.ROOT );\n\t\t\tfinal Integer typeCode = JdbcTypeNameMapper.getTypeCode( string );\n\t\t\tif ( typeCode != null ) {\n\t\t\t\treturn typeCode;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\treturn Integer.parseInt( string );\n\t\t\t}\n\t\t\tcatch (NumberFormatException ex) {\n\t\t\t\tthrow new IllegalArgumentException( String.format( \"Couldn't interpret '%s' as JDBC type code or type code name\", string ) );\n\t\t\t}\n\t\t}\n\t}\n}\n","sourceCodeStart":476,"sourceCodeEnd":499,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java#L476-L499","documentation":"The internal TypeCodeConverter converts JDBC-type settings (e.g. hibernate.type.preferred_boolean_jdbc_type, preferred_uuid_jdbc_type, preferred_instant_jdbc_type, preferred_duration_jdbc_type, preferred_array_jdbc_type). A value must be a Number, a java.sql.Types name recognized by JdbcTypeNameMapper (case-insensitive), or a string of digits. Anything else throws this IllegalArgumentException after both the name lookup and Integer.parseInt fail.","triggerScenarios":"Setting a Hibernate SqlTypes name that is not a standard java.sql.Types name, e.g. \"TIMESTAMP_UTC\", \"UUID\", \"JSON\" - these exist only in org.hibernate.type.SqlTypes with numeric codes, so the name lookup misses and parseInt fails. Likewise free-text values like \"timestamp with time zone\" throw.","commonSituations":"Copying type names from Hibernate 6+ docs or @JdbcTypeCode examples into string settings; upgrading apps that previously passed numeric codes; confusion between java.sql.Types names and Hibernate SqlTypes constants.","solutions":["Use the numeric code from org.hibernate.type.SqlTypes, e.g. TIMESTAMP_UTC = 3003, UUID = 3000","Or use a standard java.sql.Types name the mapper recognizes: \"TIMESTAMP\", \"BOOLEAN\", \"VARCHAR\", \"INTEGER\"","Check JdbcTypeNameMapper / java.sql.JdbcType for the accepted name list before writing the setting"],"exampleFix":"// before\nprops.put(\"hibernate.type.preferred_instant_jdbc_type\", \"TIMESTAMP_UTC\"); // not a java.sql.Types name\n\n// after\nprops.put(\"hibernate.type.preferred_instant_jdbc_type\",\n        String.valueOf(org.hibernate.type.SqlTypes.TIMESTAMP_UTC)); // \"3003\"","handlingStrategy":"validation","validationCode":"static boolean isValidJdbcTypeSetting(String v) {\n    String t = v.trim();\n    if (t.matches(\"\\\\d+\")) return true; // numeric type code\n    try { java.sql.JdbcType.valueOf(t.toUpperCase(java.util.Locale.ROOT)); return true; }\n    catch (IllegalArgumentException e) { return false; }\n}\n\nif (!isValidJdbcTypeSetting(props.getProperty(\"hibernate.type.preferred_instant_jdbc_type\"))) {\n    throw new IllegalStateException(\"Use a java.sql.Types name or a SqlTypes numeric code\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer numeric SqlTypes codes for Hibernate-specific types (TIMESTAMP_UTC=3003, UUID=3000)","Cross-check names against java.sql.JdbcType before writing them into settings","Add a config validation step at startup that fails fast with a clear message"],"tags":["configuration","jdbc-type","type-mapping"],"backgroundTag":"invalid-jdbc-type-code","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}