hibernate/hibernate-orm · critical · ConfigurationException

Inconsistent configuration: 'hibernate.query.plan_cache_max_

Error message

Inconsistent configuration: 'hibernate.query.plan_cache_max_size' can only be set to a value greater than zero when 'hibernate.query.plan_cache_enabled' is enabled

What it means

At SessionFactory bootstrap, QueryEngineImpl cross-checks query plan cache settings. If hibernate.query.plan_cache_max_size is explicitly set to a positive value while hibernate.query.plan_cache_enabled is false, Hibernate treats it as a contradictory configuration and fails startup with ConfigurationException. The check exists so a disabled cache with a tuned size does not silently mislead the operator.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java:194

		final boolean useCache = getBoolean(
				QUERY_PLAN_CACHE_ENABLED,
				properties,
				// enabled by default
				true
		);

		final Integer explicitMaxPlanSize = getInteger(
				QUERY_PLAN_CACHE_MAX_SIZE,
				properties
		);

		//Let's avoid some confusion and check settings consistency:
		final int appliedMaxPlanSize =
				explicitMaxPlanSize == null
						? DEFAULT_QUERY_PLAN_MAX_COUNT
						: explicitMaxPlanSize;
		if ( !useCache && explicitMaxPlanSize != null && appliedMaxPlanSize > 0 ) {
			throw new ConfigurationException( "Inconsistent configuration: '" + QUERY_PLAN_CACHE_MAX_SIZE
												+ "' can only be set to a value greater than zero when '"
												+ QUERY_PLAN_CACHE_ENABLED + "' is enabled" );
		}

		if ( appliedMaxPlanSize < 0 ) {
			throw new ConfigurationException( "Inconsistent configuration: '" + QUERY_PLAN_CACHE_MAX_SIZE
												+ "' can't be set to a negative value (to disable the query plan cache set '"
												+ QUERY_PLAN_CACHE_ENABLED + "' to 'false')" );
		}

		return useCache
				? new QueryInterpretationCacheStandardImpl( appliedMaxPlanSize, serviceRegistry )
				: new QueryInterpretationCacheDisabledImpl( serviceRegistry ); // disabled
	}

	@Override
	public void validateNamedQueries() {
		namedObjectRepository.validateNamedQueries( this );

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove hibernate.query.plan_cache_max_size when the cache is disabled.
2. Or re-enable the cache: set hibernate.query.plan_cache_enabled=true and keep the max size.
3. Keep all plan-cache settings in one configuration location so they cannot diverge.

Example fix

# before (application.properties)
hibernate.query.plan_cache_enabled=false
hibernate.query.plan_cache_max_size=2048

# after
hibernate.query.plan_cache_enabled=false
# plan_cache_max_size removed

static void checkPlanCacheSettings(java.util.Map<String, Object> cfg) {
    Boolean enabled = (Boolean) cfg.get("hibernate.query.plan_cache_enabled");
    Object size = cfg.get("hibernate.query.plan_cache_max_size");
    if (size != null && ((Number) size).intValue() > 0 && Boolean.FALSE.equals(enabled))
        throw new IllegalArgumentException(
            "plan_cache_max_size > 0 requires plan_cache_enabled=true");
}

try {
    sessionFactory = new Configuration().addProperties(props).buildSessionFactory();
} catch (org.hibernate.boot.MappingException | RuntimeException e) {
    // unwrap ConfigurationException and fail fast with the offending keys
}

When it happens

Trigger: persistence.xml, hibernate.properties, or Spring Boot application.properties containing both hibernate.query.plan_cache_enabled=false and hibernate.query.plan_cache_max_size=2048 (any value > 0). The exception is thrown while the SessionFactory is built, so the application never finishes starting.

Common situations: Disabling the plan cache during debugging but leaving an old tuned max-size setting behind; copied tuning profiles from another project; YAML property merging where a profile re-enables or disables one of the two keys.

Related errors

• Inconsistent configuration: 'hibernate.query.plan_cache_max_
• Unknown TcclLookupPrecedence - {}
• Default resolver threw exception
• Unable to access JDBC metadata
• Multiple MutationExecutorService service registrations found

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