hibernate/hibernate-orm · error · MappingException

Native temporal exclusion column option is not supported by

Error message

Native temporal exclusion column option is not supported by this dialect

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/temporal/DefaultTemporalTableSupport.java:111

	public boolean useAsOfOperator(TemporalTableStrategy strategy) {
		return strategy == TemporalTableStrategy.NATIVE;
	}

	@Override
	public boolean useTemporalRestriction(LoadQueryInfluencers influencers) {
		final var strategy =
				influencers.getSessionFactory().getSessionFactoryOptions()
						.getTemporalTableStrategy();
		return switch ( strategy ) {
			case HISTORY_TABLE -> influencers.getTemporalIdentifier() != null;
			case NATIVE -> false;
			default -> true;
		};
	}

	@Override
	public String getTemporalExclusionColumnOption() {
		throw new MappingException( "Native temporal exclusion column option is not supported by this dialect" );
	}

	@Override
	public TemporalTableStrategy getDefaultTemporalTableStrategy() {
		return HISTORY_TABLE;
	}

}

View on GitHub (pinned to fad1729dce)

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

Example fix

// before
<persistence>
  <properties>
    <property name="hibernate.temporal_table_strategy" value="native"/> <!-- MappingException on non-MariaDB -->
  </properties>

// after: drop back to the default history-table strategy
<property name="hibernate.temporal_table_strategy" value="history_table"/>

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast at bootstrap with a clear message instead of Hibernate's MappingException
Dialect dialect = serviceRegistry.getService(ConnectionProviderDialect.class) != null ? null : null;
// practical form: check the support class once you have the Dialect
static boolean supportsNativeTemporal(Dialect dialect) {
    return !(dialect.getTemporalTableSupport() instanceof DefaultTemporalTableSupport);
}

if (config.get("hibernate.temporal_table_strategy").equals("native")
        && !supportsNativeTemporal(dialect)) {
    throw new ConfigurationException("NATIVE temporal strategy needs a dialect with native temporal table support");
}

Try / catch

try {
    sessionFactory = new Configuration().configure().buildSessionFactory();
} catch (MappingException e) {
    if (e.getMessage().startsWith("Native temporal exclusion column option")) {
        // strategy/dialect mismatch: drop NATIVE or remove @Excluded, then rebuild
        throw new ConfigurationException("Set temporal strategy to history_table or remove @Excluded", e);
    }
    throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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