hibernate/hibernate-orm · error · IllegalArgumentException

JDBC type-code [%s (%s)] not known to have a corresponding L

Error message

JDBC type-code [%s (%s)] not known to have a corresponding LOB equivalent

What it means

LobTypeMappings.getLobCodeTypeMapping() answers the LOB-equivalent java.sql.Types code for exactly three families: binary (BLOB/BINARY/VARBINARY/LONGVARBINARY -> BLOB), char (CLOB/CHAR/VARCHAR/LONGVARCHAR -> CLOB) and nchar (NCLOB/NCHAR/NVARCHAR/LONGNVARCHAR -> NCLOB). Any other code has no LOB variant and throws IllegalArgumentException naming the offending code and type name.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/LobTypeMappings.java:51

				jdbcTypeCode == Types.LONGVARCHAR ||

				// NCLOB mappings
				jdbcTypeCode == Types.NCLOB ||
				jdbcTypeCode == Types.NCHAR ||
				jdbcTypeCode == Types.NVARCHAR ||
				jdbcTypeCode == Types.LONGNVARCHAR;
	}

	public static int getLobCodeTypeMapping(final int jdbcTypeCode) {
		return switch ( jdbcTypeCode ) {
			// BLOB mappings
			case Types.BLOB, Types.BINARY, Types.VARBINARY, Types.LONGVARBINARY -> Types.BLOB;
			// CLOB mappings
			case Types.CLOB, Types.CHAR, Types.VARCHAR, Types.LONGVARCHAR -> Types.CLOB;
			// NCLOB mappings
			case Types.NCLOB, Types.NCHAR, Types.NVARCHAR, Types.LONGNVARCHAR -> Types.NCLOB;
			// Anything else:
			default -> throw new IllegalArgumentException(
					String.format(
							Locale.ROOT,
							"JDBC type-code [%s (%s)] not known to have a corresponding LOB equivalent",
							jdbcTypeCode,
							JdbcTypeNameMapper.getTypeName( jdbcTypeCode )
					) );
		};
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Guard the call with LobTypeMappings.isMappedToKnownLobCode(jdbcTypeCode) and only derive LOB variants for the binary/char/nchar families.
If a LOB was intended, map the attribute explicitly to Types.BLOB/CLOB/NCLOB instead of deriving it from a non-lob code.
Audit custom dialect/type code for unconditional calls to getLobCodeTypeMapping().

Example fix

// before
int lobCode = LobTypeMappings.getLobCodeTypeMapping(jdbcTypeCode); // throws for Types.INTEGER

// after: only LOB families have equivalents
if (LobTypeMappings.isMappedToKnownLobCode(jdbcTypeCode)) {
    int lobCode = LobTypeMappings.getLobCodeTypeMapping(jdbcTypeCode);
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Guard the LOB derivation with the family check Hibernate provides
if (LobTypeMappings.isMappedToKnownLobCode(jdbcTypeCode)) {
    int lobCode = LobTypeMappings.getLobCodeTypeMapping(jdbcTypeCode);
    // ... build the LOB variant
} else {
    // no LOB equivalent exists for this code - keep the original type
}

Type guard

static boolean hasLobEquivalent(int jdbcTypeCode) {
    return LobTypeMappings.isMappedToKnownLobCode(jdbcTypeCode);
}

Try / catch

try {
    return LobTypeMappings.getLobCodeTypeMapping(jdbcTypeCode);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("not known to have a corresponding LOB equivalent")) {
        // this jdbcTypeCode has no LOB variant: map to BLOB/CLOB/NCLOB explicitly if a LOB was intended
    } else {
        throw e;
    }
}

Prevention

Never call LOB-variant derivation for non-binary/non-char type codes
Unit-test custom dialect/type code against the full SqlTypes set
Map intended LOBs explicitly instead of deriving them

When it happens

Trigger: Calling getLobCodeTypeMapping() (directly, or through dialect/type-building code that materializes LOB variants, e.g. wrapping a type as LOB or nationalized) with a non-lob-family code such as Types.INTEGER, Types.DATE, Types.ARRAY or Types.STRUCT.

Common situations: Custom dialects or integrators that blindly derive a LOB variant for every JDBC type; programmatic type building with SqlTypes codes fed into the LOB helper; copy-pasted type-contribution code assuming all codes have LOB equivalents.

Related errors

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