hibernate/hibernate-orm · error · MappingException

illegal identity column type

Error message

illegal identity column type

What it means

CockroachDBIdentityColumnSupport.getIdentityColumnString only accepts TINYINT/SMALLINT (serial2), INTEGER (serial4) and BIGINT (serial8) identity columns; every other java.sql.Types code falls through to a MappingException 'illegal identity column type'. Hibernate calls this while building the insert/DDL mapping for an entity whose primary key uses identity generation on the CockroachDB dialect. The restriction exists because CockroachDB SERIAL types map to integer bit_reversed/unique_rowid values that only fit integer types.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/identity/CockroachDBIdentityColumnSupport.java:42

	public String getIdentitySelectString(String table, String column, int type) {
		return "select 1";
	}

	@Override
	public String getIdentityColumnString(int type) {
		// Note that the unique_rowid() function used to generated values with serial_normalization=rowid (default)
		// will always produce INT8 (Types.BIGINT) values which might not fit other data types.
		// See https://www.cockroachlabs.com/docs/stable/serial.html
		switch ( type ) {
			case Types.TINYINT:
			case Types.SMALLINT:
				return "serial2 not null";
			case Types.INTEGER:
				return "serial4 not null";
			case Types.BIGINT:
				return "serial8 not null";
			default:
				throw new MappingException( "illegal identity column type");
		}
	}

	@Override
	public boolean hasDataTypeInIdentityColumn() {
		return false;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Change the id to an integer type (Long/Integer/Short) so identity/serial works on CockroachDB
  2. Keep UUID ids but drop identity generation - assign values client-side with @GeneratedValue(strategy = GenerationType.UUID) or @UuidGenerator
  3. Use a sequence/table generator with a compatible type instead of identity
  4. If DDL already exists, make the column type agree with an integer serial type before letting Hibernate validate the mapping

Example fix

// before
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private UUID id;

// after
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;
Defensive patterns

Strategy: validation

Validate before calling

// At bootstrap, fail fast with a clear message instead of a MappingException
EntityType<?> idType = sessionFactory.getMetamodel().entity(Person.class).getIdType();
boolean integerId = Number.class.isAssignableFrom(idType.getJavaType());
if (!integerId && generationUsesIdentity(Person.class)) {
    throw new IllegalStateException("CockroachDB identity generation requires integer id types");
}

Try / catch

try {
    sessionFactory = new Configuration().addAnnotatedClass(Person.class).buildSessionFactory();
}
catch (MappingException e) {
    if (e.getMessage().contains("illegal identity column type")) {
        throw new IllegalStateException("Switch the entity id to Long/Integer or use a UUID generator (CockroachDB serial columns are integer-only)", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: With the CockroachDB dialect, an entity has @GeneratedValue(strategy = GenerationType.IDENTITY) (or an 'identity' mapping) on an id whose JDBC type is not an integer - e.g. UUID (Types.OTHER/VARCHAR), String, NUMERIC/DECIMAL, or an enum mapped to TINYINT with a non-standard code. The exception surfaces when Hibernate binds the mapping (SessionFactory bootstrap).

Common situations: Reusing a UUID-based entity model from Postgres on CockroachDB; domain models with BigDecimal ids; switching hibernate.dialect to CockroachDialect while keeping @GeneratedValue IDENTITY on non-integer keys; QUuid columns created outside Hibernate then reverse-engineered.

Related errors

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