hibernate/hibernate-orm · error · IllegalArgumentException

Couldn't interpret '%s' as JDBC type code or type code name

Error message

Couldn't interpret '%s' as JDBC type code or type code name

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java:494

		public static final TypeCodeConverter INSTANCE = new TypeCodeConverter();

		@Override
		@Nonnull
		public Integer convert(@Nonnull Object value) {
			if ( value instanceof Number number ) {
				return number.intValue();
			}

			final String string = value.toString().toUpperCase( Locale.ROOT );
			final Integer typeCode = JdbcTypeNameMapper.getTypeCode( string );
			if ( typeCode != null ) {
				return typeCode;
			}
			try {
				return Integer.parseInt( string );
			}
			catch (NumberFormatException ex) {
				throw new IllegalArgumentException( String.format( "Couldn't interpret '%s' as JDBC type code or type code name", string ) );
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use the numeric code from org.hibernate.type.SqlTypes, e.g. TIMESTAMP_UTC = 3003, UUID = 3000
2. Or use a standard java.sql.Types name the mapper recognizes: "TIMESTAMP", "BOOLEAN", "VARCHAR", "INTEGER"
3. Check JdbcTypeNameMapper / java.sql.JdbcType for the accepted name list before writing the setting

Example fix

// before
props.put("hibernate.type.preferred_instant_jdbc_type", "TIMESTAMP_UTC"); // not a java.sql.Types name

// after
props.put("hibernate.type.preferred_instant_jdbc_type",
        String.valueOf(org.hibernate.type.SqlTypes.TIMESTAMP_UTC)); // "3003"

static boolean isValidJdbcTypeSetting(String v) {
    String t = v.trim();
    if (t.matches("\\d+")) return true; // numeric type code
    try { java.sql.JdbcType.valueOf(t.toUpperCase(java.util.Locale.ROOT)); return true; }
    catch (IllegalArgumentException e) { return false; }
}

if (!isValidJdbcTypeSetting(props.getProperty("hibernate.type.preferred_instant_jdbc_type"))) {
    throw new IllegalStateException("Use a java.sql.Types name or a SqlTypes numeric code");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• JDBC type-code [%s (%s)] not known to have a corresponding L
• The {storageEngine} storage engine is not supported
• Unknown Cache Mode: " + setting
• Unrecognized graph_parser_mode value : " + graphParserMode +
• Audit graph mutation plan used with non-graph action queue

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