{"record":{"id":"8acf44c5a6659084","repo":"hibernate/hibernate-orm","slug":"unknown-type-sqltypecode","errorCode":null,"errorMessage":"unknown type: {sqlTypeCode}","messagePattern":"unknown type: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java","lineNumber":631,"sourceCode":"\n\t\t\tcase CHAR -> \"char($l)\";\n\t\t\tcase VARCHAR -> \"varchar($l)\";\n\t\t\tcase CLOB -> \"clob\";\n\n\t\t\tcase NCHAR -> \"nchar($l)\";\n\t\t\tcase NVARCHAR -> \"nvarchar($l)\";\n\t\t\tcase NCLOB -> \"nclob\";\n\n\t\t\tcase BINARY -> \"binary($l)\";\n\t\t\tcase VARBINARY -> \"varbinary($l)\";\n\t\t\tcase BLOB -> \"blob\";\n\n\t\t\t// by default use the LOB mappings for the \"long\" types\n\t\t\tcase LONG32VARCHAR -> columnType( CLOB );\n\t\t\tcase LONG32NVARCHAR -> columnType( NCLOB );\n\t\t\tcase LONG32VARBINARY -> columnType( BLOB );\n\n\t\t\tdefault -> throw new IllegalArgumentException( \"unknown type: \" + sqlTypeCode );\n\t\t};\n\t}\n\n\t/**\n\t * Does this dialect strip trailing spaces from values stored\n\t * in columns of type {@code char(n)}?\n\t * MySQL and Sybase are the main offenders here.\n\t */\n\tpublic boolean stripsTrailingSpacesFromChar() {\n\t\treturn false;\n\t}\n\n\t/**\n\t * The SQL type to use in {@code cast( ... as ... )} expressions when\n\t * casting to the target type represented by the given JDBC type code.\n\t *\n\t * @param sqlTypeCode The JDBC type code representing the target type\n\t * @return The SQL type to use in {@code cast()}","sourceCodeStart":613,"sourceCodeEnd":649,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java#L613-L649","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: custom dialect overrides columnType with a narrow switch\n// -> IllegalArgumentException: unknown type: 3005 (SqlTypes.JSON)\n\n// after\nclass MyDialect extends PostgreSQLDialect {\n    @Override\n    protected String columnType(int sqlTypeCode) {\n        return switch (sqlTypeCode) {\n            case SqlTypes.JSON -> \"jsonb\";\n            default -> super.columnType(sqlTypeCode);\n        };\n    }\n}","handlingStrategy":"fallback","validationCode":"// startup smoke test: boot the factory against the mapped entities; columnType gaps fail here, not at first DDL generation\ntry {\n    SessionFactory sf = new Configuration().addAnnotatedClass(Item.class).buildSessionFactory();\n    sf.close();\n} catch (IllegalArgumentException e) {\n    throw new IllegalStateException(\"A mapped JDBC type code has no column type in this dialect: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return super.columnType(sqlTypeCode);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"unknown type:\")) {\n        return \"varchar(255)\"; // or another safe fallback; log loudly so the gap gets fixed properly\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["hibernate","dialect","jdbc-type","schema-generation","ddl","mapping"],"backgroundTag":"unsupported-jdbc-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}