hibernate/hibernate-orm · error · PersistenceException

Property %s was set to `%s`, which is not compatible with th

Error message

Property %s was set to `%s`, which is not compatible with the expected type %s

What it means

The setting hibernate.enhancer.bytecodeprovider.instance (BytecodeSettings.BYTECODE_PROVIDER_INSTANCE) must hold an actual org.hibernate.bytecode.spi.BytecodeProvider INSTANCE, not a name. getExplicitBytecodeProvider checks the integration settings and persistence-unit properties, and any non-null value that is not a BytecodeProvider throws this PersistenceException at EntityManagerFactory creation, echoing the offending value.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java:432

			@Override
			public BytecodeProvider getBytecodeProvider() {
				return overriddenBytecodeProvider;
			}
		};
	}

	private BytecodeProvider getExplicitBytecodeProvider(
			Map<?, ?> integrationSettings,
			PersistenceUnitInfo persistenceUnit) {
		// again, prefer integration settings
		var setting = integrationSettings.get( BYTECODE_PROVIDER_INSTANCE );
		if ( setting == null ) {
			setting = persistenceUnit.getProperties().get( BYTECODE_PROVIDER_INSTANCE );
		}

		if ( setting != null && ! (setting instanceof BytecodeProvider) ) {
			throw new PersistenceException( String.format( Locale.ROOT,
					"Property %s was set to `%s`, which is not compatible with the expected type %s",
					BYTECODE_PROVIDER_INSTANCE,
					setting,
					BytecodeProvider.class.getName()
			) );
		}

		return (BytecodeProvider) setting;
	}


	private static class ProviderUtilImpl implements ProviderUtil {
		public static final ProviderUtilImpl INSTANCE = new ProviderUtilImpl();

		private final MetadataCache cache = new MetadataCache();

		@Override
		public LoadState isLoadedWithoutReference(Object proxy, String property) {

View on GitHub (pinned to fad1729dce)

Solutions

To select a provider by name, use hibernate.bytecode.provider = "bytebuddy" instead
To inject a pre-built provider, pass the instance: props.put("hibernate.enhancer.bytecodeprovider.instance", myBytecodeProvider)
Remove the setting entirely if the default provider is fine

Example fix

// before
props.put("hibernate.enhancer.bytecodeprovider.instance", "bytebuddy"); // String -> PersistenceException

// after
props.put("hibernate.bytecode.provider", "bytebuddy"); // select by name
// or inject an instance:
// props.put("hibernate.enhancer.bytecodeprovider.instance", myBytecodeProvider);

Defensive patterns

Strategy: type-guard

Validate before calling

Object candidate = props.get("hibernate.enhancer.bytecodeprovider.instance");
if (candidate != null && !(candidate instanceof org.hibernate.bytecode.spi.BytecodeProvider)) {
    // switch to the name-based setting
    props.put("hibernate.bytecode.provider", String.valueOf(candidate));
    props.remove("hibernate.enhancer.bytecodeprovider.instance");
}

Type guard

static org.hibernate.bytecode.spi.BytecodeProvider asBytecodeProvider(Object v) {
    return (v == null || v instanceof org.hibernate.bytecode.spi.BytecodeProvider p)
            ? (org.hibernate.bytecode.spi.BytecodeProvider) v
            : null; // null -> drop the setting, use name-based selection
}

Prevention

Use hibernate.bytecode.provider for name-based selection
Reserve the ...instance setting for pre-built BytecodeProvider objects you constructed yourself
Never put class-name strings in the instance setting

When it happens

Trigger: props.put("hibernate.enhancer.bytecodeprovider.instance", "bytebuddy") - a String instead of an instance; likewise passing a Class object or a fully-qualified class name string.

Common situations: Copy-pasting the NAME-based setting into the INSTANCE slot; migrating from hibernate.bytecode.provider (name string) to the instance setting without changing the value type; configuration frameworks coercing the value to String.

Related errors

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