What causes "unknown type: {sqlTypeCode}" in hibernate/hibernate-orm?

Upgrade the dialect (and Hibernate) to a version whose columnType covers the code

hibernate/hibernate-orm · error · IllegalArgumentException

unknown type: {sqlTypeCode}

Error message

unknown type: {sqlTypeCode}

What it means

Dialect.columnType(int sqlTypeCode) is the base switch mapping JDBC type codes (SqlTypes constants) to column type names for DDL. The default branch throws IllegalArgumentException('unknown type: <code>') for any code this dialect does not handle — typically a newer or exotic SqlTypes constant (JSON, SQLJSON, GEOMETRY, VECTOR, ...) reaching a dialect (often a custom subclass) whose switch does not cover it. It usually surfaces at SessionFactory boot or schema export.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java:631

			case CHAR -> "char($l)";
			case VARCHAR -> "varchar($l)";
			case CLOB -> "clob";

			case NCHAR -> "nchar($l)";
			case NVARCHAR -> "nvarchar($l)";
			case NCLOB -> "nclob";

			case BINARY -> "binary($l)";
			case VARBINARY -> "varbinary($l)";
			case BLOB -> "blob";

			// by default use the LOB mappings for the "long" types
			case LONG32VARCHAR -> columnType( CLOB );
			case LONG32NVARCHAR -> columnType( NCLOB );
			case LONG32VARBINARY -> columnType( BLOB );

			default -> throw new IllegalArgumentException( "unknown type: " + sqlTypeCode );
		};
	}

	/**
	 * Does this dialect strip trailing spaces from values stored
	 * in columns of type {@code char(n)}?
	 * MySQL and Sybase are the main offenders here.
	 */
	public boolean stripsTrailingSpacesFromChar() {
		return false;
	}

	/**
	 * The SQL type to use in {@code cast( ... as ... )} expressions when
	 * casting to the target type represented by the given JDBC type code.
	 *
	 * @param sqlTypeCode The JDBC type code representing the target type
	 * @return The SQL type to use in {@code cast()}

View on GitHub (pinned to fad1729dce)

Solutions

Upgrade the dialect (and Hibernate) to a version whose columnType covers the code
In a custom dialect, override columnType to add the code and delegate everything else: default -> super.columnType(sqlTypeCode)
Give the column an explicit definition the dialect passes through: @Column(columnDefinition = "jsonb")
As a last resort map the attribute to a code the dialect supports (e.g. VARBINARY/VARCHAR) with a converter

Example fix

// before: custom dialect overrides columnType with a narrow switch
// -> IllegalArgumentException: unknown type: 3005 (SqlTypes.JSON)

// after
class MyDialect extends PostgreSQLDialect {
    @Override
    protected String columnType(int sqlTypeCode) {
        return switch (sqlTypeCode) {
            case SqlTypes.JSON -> "jsonb";
            default -> super.columnType(sqlTypeCode);
        };
    }
}

Defensive patterns

Strategy: fallback

Validate before calling

// startup smoke test: boot the factory against the mapped entities; columnType gaps fail here, not at first DDL generation
try {
    SessionFactory sf = new Configuration().addAnnotatedClass(Item.class).buildSessionFactory();
    sf.close();
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("A mapped JDBC type code has no column type in this dialect: " + e.getMessage(), e);
}

Try / catch

try {
    return super.columnType(sqlTypeCode);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("unknown type:")) {
        return "varchar(255)"; // or another safe fallback; log loudly so the gap gets fixed properly
    }
    throw e;
}

Prevention

After any Hibernate upgrade, boot the SessionFactory and generate schema in CI to catch unmapped JDBC codes
In custom dialects always delegate unknown codes to super.columnType instead of ending the switch
Prefer @Column(columnDefinition=...) or upgrading the dialect over open-ended fallbacks

When it happens

Trigger: An entity maps a type whose JDBC code is outside the dialect's switch: @JdbcTypeCode(SqlTypes.JSON) on a dialect without JSON mapping, new Hibernate JDBC codes (e.g. TIMESTAMP_UTC-family) hitting an older custom dialect that overrode columnType with a narrower switch, or schema validation/export touching the unmapped code.

Common situations: Hibernate upgrades introducing new SqlTypes codes that pre-existing custom dialects never see; community/third-party dialects lagging the core version; introducing JSON, geometry, or vector columns on databases whose dialect predates them; copying an old Dialect subclass forward between major versions.

Related errors

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