{"record":{"id":"4dfaff46dea2305f","repo":"hibernate/hibernate-orm","slug":"native-temporal-exclusion-column-option-is-not-sup","errorCode":null,"errorMessage":"Native temporal exclusion column option is not supported by this dialect","messagePattern":"Native temporal exclusion column option is not supported by this dialect","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/temporal/DefaultTemporalTableSupport.java","lineNumber":111,"sourceCode":"\tpublic boolean useAsOfOperator(TemporalTableStrategy strategy) {\n\t\treturn strategy == TemporalTableStrategy.NATIVE;\n\t}\n\n\t@Override\n\tpublic boolean useTemporalRestriction(LoadQueryInfluencers influencers) {\n\t\tfinal var strategy =\n\t\t\t\tinfluencers.getSessionFactory().getSessionFactoryOptions()\n\t\t\t\t\t\t.getTemporalTableStrategy();\n\t\treturn switch ( strategy ) {\n\t\t\tcase HISTORY_TABLE -> influencers.getTemporalIdentifier() != null;\n\t\t\tcase NATIVE -> false;\n\t\t\tdefault -> true;\n\t\t};\n\t}\n\n\t@Override\n\tpublic String getTemporalExclusionColumnOption() {\n\t\tthrow new MappingException( \"Native temporal exclusion column option is not supported by this dialect\" );\n\t}\n\n\t@Override\n\tpublic TemporalTableStrategy getDefaultTemporalTableStrategy() {\n\t\treturn HISTORY_TABLE;\n\t}\n\n}\n","sourceCodeStart":93,"sourceCodeEnd":120,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/temporal/DefaultTemporalTableSupport.java#L93-L120","documentation":"Hibernate 7 maps SQL:2011 temporal (system-versioned) tables. When a property is annotated @Excluded (excluded from temporal versioning) and the bootstrap temporal strategy is NATIVE, PropertyBinder.addTemporalExcludedColumnOptions must append the dialect's exclusion column option to the column DDL and calls dialect.getTemporalTableSupport().getTemporalExclusionColumnOption(). DefaultTemporalTableSupport -- the base for dialects without native temporal tables -- throws MappingException('Native temporal exclusion column option is not supported by this dialect') at mapping/boot time.","triggerScenarios":"Configuration sets the temporal table strategy to NATIVE (e.g. hibernate.temporal_table_strategy=native or the equivalent bootstrap setting) AND an entity attribute carries @Excluded, while the dialect's TemporalTableSupport is the default (only MariaDBTemporalTableSupport implements a real option). The MappingException is thrown while the SessionFactory is built, during mapping binding.","commonSituations":"Enabling the NATIVE temporal strategy globally (copied from MariaDB examples) on PostgreSQL/Oracle/SQL Server test runs; using @Excluded on temporal entities while the target DB has no native system-versioning support; upgrading to Hibernate 7 and experimenting with the new temporal-table mapping.","solutions":["Use the default HISTORY_TABLE strategy instead of NATIVE unless the database truly supports native temporal tables","Remove @Excluded from the property so no exclusion column option is needed","Target a dialect whose TemporalTableSupport implements getTemporalExclusionColumnOption (MariaDB)","Subclass your dialect and override getTemporalTableSupport() to return a support object providing the correct option string for your DB"],"exampleFix":"// before\n<persistence>\n  <properties>\n    <property name=\"hibernate.temporal_table_strategy\" value=\"native\"/> <!-- MappingException on non-MariaDB -->\n  </properties>\n\n// after: drop back to the default history-table strategy\n<property name=\"hibernate.temporal_table_strategy\" value=\"history_table\"/>","handlingStrategy":"validation","validationCode":"// Fail fast at bootstrap with a clear message instead of Hibernate's MappingException\nDialect dialect = serviceRegistry.getService(ConnectionProviderDialect.class) != null ? null : null;\n// practical form: check the support class once you have the Dialect\nstatic boolean supportsNativeTemporal(Dialect dialect) {\n    return !(dialect.getTemporalTableSupport() instanceof DefaultTemporalTableSupport);\n}\n\nif (config.get(\"hibernate.temporal_table_strategy\").equals(\"native\")\n        && !supportsNativeTemporal(dialect)) {\n    throw new ConfigurationException(\"NATIVE temporal strategy needs a dialect with native temporal table support\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = new Configuration().configure().buildSessionFactory();\n} catch (MappingException e) {\n    if (e.getMessage().startsWith(\"Native temporal exclusion column option\")) {\n        // strategy/dialect mismatch: drop NATIVE or remove @Excluded, then rebuild\n        throw new ConfigurationException(\"Set temporal strategy to history_table or remove @Excluded\", e);\n    }\n    throw e;\n}","preventionTips":["Only enable hibernate.temporal_table_strategy=native on databases with native system-versioning (e.g. MariaDB)","Scan the codebase for @Excluded usages before switching the temporal strategy","Add a bootstrap smoke test per target dialect so mapping errors surface in CI, not in production"],"tags":["hibernate","temporal-tables","mapping","dialect","bootstrap","system-versioned"],"backgroundTag":"native-temporal-table-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}