What causes "Unable to determine SQL type name for column '%s' of table '%s'" in hibernate/hibernate-orm?

Read the MappingException's cause - it names the real failure (usually an unknown JDBC type code) for the affected column and table.

hibernate/hibernate-orm · error · MappingException

Unable to determine SQL type name for column '%s' of table '

Error message

Unable to determine SQL type name for column '%s' of table '%s'

What it means

Thrown from Column#isLob() while Hibernate resolves a column's SQL type during metadata building or DDL generation. The calls getSqlTypeCode(mapping) plus the DdlTypeRegistry descriptor lookup raised an unexpected exception, which Hibernate wraps together with the column and table name. In practice the configured dialect has no DDL type registered for the column's JDBC type code, so Hibernate cannot turn the mapping into a SQL type name.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Column.java:561

	public boolean isSqlTypeLob(Metadata mapping) {
		final var database = mapping.getDatabase();
		final var ddlTypeRegistry = database.getTypeConfiguration().getDdlTypeRegistry();
		final var dialect = database.getDialect();
		if ( sqlTypeLob == null ) {
			try {
				final int typeCode = getSqlTypeCode( mapping );
				final var ddlType = ddlTypeRegistry.getDescriptor( typeCode );
				sqlTypeLob =
						ddlType == null
								? JdbcType.isLob( typeCode )
								: ddlType.isLob( getColumnSize( dialect, mapping ) );
			}
			catch ( MappingException cause ) {
				throw cause;
			}
			catch ( Exception cause ) {
				throw new MappingException(
						String.format(
								Locale.ROOT,
								"Unable to determine SQL type name for column '%s' of table '%s'",
								getName(),
								getValue().getTable().getName()
						),
						cause
				);
			}
		}
		return sqlTypeLob;
	}

	public void setUnique(boolean unique) {
		this.unique = unique;
	}

	public String getUniqueKeyName() {

View on GitHub (pinned to fad1729dce)

Solutions

Read the MappingException's cause - it names the real failure (usually an unknown JDBC type code) for the affected column and table.
Use the Hibernate 6+ built-in dialect for your database instead of a Hibernate 5 dialect class, then retry; modern dialects register most codes.
Register the missing DDL type for the code, e.g. via a TypeContributor or dialect customization that registers the column type / DdlType on the DdlTypeRegistry.
Fix the custom type to return a SqlTypes code every dialect can render (e.g. SqlTypes.NUMERIC, SqlTypes.VARCHAR) if the vendor type is not strictly required.

Example fix

// before
public class MoneyType implements UserType<Money> {
    @Override
    public int getSqlTypeCode() {
        return 9988; // vendor code the dialect never registered
    }
}

// after
public class MoneyType implements UserType<Money> {
    @Override
    public int getSqlTypeCode() {
        return SqlTypes.NUMERIC; // a code every dialect can render
    }
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    sessionFactory = new MetadataSources(registry)
            .buildMetadata()
            .buildSessionFactory();
} catch (MappingException e) {
    // message names the column + table; the cause holds the real reason
    Throwable root = e.getCause() != null ? e.getCause() : e;
    throw new IllegalStateException(
        "Mapping failed: " + e.getMessage() + " / cause: " + root, e);
}

Prevention

Boot the SessionFactory in a smoke test with hbm2ddl.auto=validate in CI so unregistered type codes fail before deployment.
Keep the Hibernate version and its dialect in lockstep; avoid custom Dialect subclasses when a built-in one exists.
Prefer @JdbcTypeCode with standard SqlTypes values over hand-written getSqlTypeCode() overrides.
Register vendor DDL types through a TypeContributor declared in META-INF/services so they load automatically.

When it happens

Trigger: A custom UserType/BasicUserType whose getSqlTypeCode() returns a vendor code the dialect never registered; array, JSON or SQLXML columns used with a dialect that lacks the DDL type; running a legacy Hibernate 5 dialect class on Hibernate 6 where type registration moved to DdlTypeRegistry; hbm2ddl validate/update at SessionFactory boot touching the unmapped column.

Common situations: Hibernate 5 to 6 upgrades with an old custom Dialect subclass; custom value types for database-specific types (vendor arrays, special varchar types) registered only partially; using @JdbcTypeCode with an exotic SqlTypes constant; CI booting with hbm2ddl.auto=validate against a new column type.

Related errors

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