{"record":{"id":"4a45f634abf58e3f","repo":"hibernate/hibernate-orm","slug":"illegal-identity-column-type-4a45f6","errorCode":null,"errorMessage":"illegal identity column type","messagePattern":"illegal identity column type","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/identity/CockroachDBIdentityColumnSupport.java","lineNumber":42,"sourceCode":"\tpublic String getIdentitySelectString(String table, String column, int type) {\n\t\treturn \"select 1\";\n\t}\n\n\t@Override\n\tpublic String getIdentityColumnString(int type) {\n\t\t// Note that the unique_rowid() function used to generated values with serial_normalization=rowid (default)\n\t\t// will always produce INT8 (Types.BIGINT) values which might not fit other data types.\n\t\t// See https://www.cockroachlabs.com/docs/stable/serial.html\n\t\tswitch ( type ) {\n\t\t\tcase Types.TINYINT:\n\t\t\tcase Types.SMALLINT:\n\t\t\t\treturn \"serial2 not null\";\n\t\t\tcase Types.INTEGER:\n\t\t\t\treturn \"serial4 not null\";\n\t\t\tcase Types.BIGINT:\n\t\t\t\treturn \"serial8 not null\";\n\t\t\tdefault:\n\t\t\t\tthrow new MappingException( \"illegal identity column type\");\n\t\t}\n\t}\n\n\t@Override\n\tpublic boolean hasDataTypeInIdentityColumn() {\n\t\treturn false;\n\t}\n}\n","sourceCodeStart":24,"sourceCodeEnd":51,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/identity/CockroachDBIdentityColumnSupport.java#L24-L51","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Change the id to an integer type (Long/Integer/Short) so identity/serial works on CockroachDB","Keep UUID ids but drop identity generation - assign values client-side with @GeneratedValue(strategy = GenerationType.UUID) or @UuidGenerator","Use a sequence/table generator with a compatible type instead of identity","If DDL already exists, make the column type agree with an integer serial type before letting Hibernate validate the mapping"],"exampleFix":"// before\n@Id\n@GeneratedValue(strategy = GenerationType.IDENTITY)\nprivate UUID id;\n\n// after\n@Id\n@GeneratedValue(strategy = GenerationType.UUID)\nprivate UUID id;","handlingStrategy":"validation","validationCode":"// At bootstrap, fail fast with a clear message instead of a MappingException\nEntityType<?> idType = sessionFactory.getMetamodel().entity(Person.class).getIdType();\nboolean integerId = Number.class.isAssignableFrom(idType.getJavaType());\nif (!integerId && generationUsesIdentity(Person.class)) {\n    throw new IllegalStateException(\"CockroachDB identity generation requires integer id types\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = new Configuration().addAnnotatedClass(Person.class).buildSessionFactory();\n}\ncatch (MappingException e) {\n    if (e.getMessage().contains(\"illegal identity column type\")) {\n        throw new IllegalStateException(\"Switch the entity id to Long/Integer or use a UUID generator (CockroachDB serial columns are integer-only)\", e);\n    }\n    throw e;\n}","preventionTips":["On CockroachDB, only map TINYINT/SMALLINT/INTEGER/BIGINT ids with identity/serial generation","Use @UuidGenerator/@GeneratedValue(strategy = GenerationType.UUID) for UUID keys","Run a bootstrap smoke test that builds the SessionFactory in CI to catch mapping failures before deployment"],"tags":["hibernate","cockroachdb","identity","mapping","ddl"],"backgroundTag":"identity-generation-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}