hibernate/hibernate-orm · error · HibernateException

Multiple SchemaManagementTool service registrations found vi

Error message

Multiple SchemaManagementTool service registrations found via ServiceLoader; specify one explicitly via 'hibernate.schema_management_tool'

What it means

At bootstrap Hibernate discovers the SchemaManagementTool via java.util.ServiceLoader (META-INF/services entries). If more than one implementation is discoverable, picking one would be arbitrary, so SchemaManagementToolInitiator.discover throws and tells you to pin the choice via the hibernate.schema_management_tool setting. Two jars on the classpath each registering the service is the typical cause.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/internal/SchemaManagementToolInitiator.java:47

				.<SchemaManagementTool>resolveDefaultableStrategy( SchemaManagementTool.class,
						configurationValues.get( SCHEMA_MANAGEMENT_TOOL ),
						() -> {
							final var discovered = discover( registry.requireService( ClassLoaderService.class ) );
							if ( discovered != null ) {
								return discovered;
							}
							return registry.requireService( JdbcServices.class ).getDialect()
									.getFallbackSchemaManagementTool( configurationValues, registry );
						} );
	}

	private static SchemaManagementTool discover(ClassLoaderService classLoaderService) {
		final var discovered = classLoaderService.loadJavaServices( SchemaManagementTool.class );
		final var iterator = discovered.iterator();
		if ( iterator.hasNext() ) {
			final var selected = iterator.next();
			if ( iterator.hasNext() ) {
				throw new HibernateException(
						"Multiple SchemaManagementTool service registrations found via ServiceLoader; "
						+ "specify one explicitly via '" + SCHEMA_MANAGEMENT_TOOL + "'" );
			}
			return selected;
		}
		else {
			return null;
		}
	}

	@Nonnull
	@Override
	public Class<SchemaManagementTool> getServiceInitiated() {
		return SchemaManagementTool.class;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Run the dependency tree (mvn dependency:tree, gradle dependencies) and exclude the duplicate hibernate-core (or the duplicate provider jar) so exactly one registration remains on the classpath.
If both tools must coexist, set hibernate.schema_management_tool to the fully-qualified class name of the implementation you want.
In fat jars, inspect the merged META-INF/services/org.hibernate.tool.schema.spi.SchemaManagementTool file for duplicated lines and fix the shading/assembly configuration.

Example fix

// before: two hibernate-core versions on the classpath
implementation("org.hibernate.orm:hibernate-core:6.2.Final")
implementation("some-lib:some-lib:1.0") // transitively pulls hibernate-core 6.4

// after: align to one version
implementation(platform("org.hibernate.orm:hibernate-core-bom:6.4.Final"))
implementation("org.hibernate.orm:hibernate-core")
implementation("some-lib:some-lib:1.0") { exclude(group = "org.hibernate.orm") }

Defensive patterns

Strategy: validation

Validate before calling

List<SchemaManagementTool> found = new ArrayList<>();
for (SchemaManagementTool t : ServiceLoader.load(SchemaManagementTool.class, getClass().getClassLoader())) {
    found.add(t);
}
if (found.size() > 1) {
    throw new IllegalStateException("Ambiguous SchemaManagementTool providers on classpath: " + found);
}

Try / catch

try {
    emf = Persistence.createEntityManagerFactory("pu");
} catch (PersistenceException e) {
    if (e.getCause() instanceof HibernateException h
            && h.getMessage() != null && h.getMessage().contains("Multiple SchemaManagementTool")) {
        // dedupe the classpath or set hibernate.schema_management_tool explicitly, then retry bootstrap
    } else { throw e; }
}

Prevention

Lock Hibernate to a single version with a BOM/dependencyManagement block.
Run duplicate-dependency checks in CI (maven-enforcer, Gradle failOnVersionConflict).
When shipping a custom SchemaManagementTool, exclude or consolidate service registrations explicitly.

When it happens

Trigger: Two or more classpath entries provide META-INF/services/org.hibernate.tool.schema.spi.SchemaManagementTool: hibernate-core present twice in different versions (dependency mediation), a fat/shaded jar that merged service files from two Hibernate artifacts, or an in-house/custom SchemaManagementTool packaged alongside the default one. Thrown while the SessionFactory/EntityManagerFactory is being built.

Common situations: Maven/Gradle conflicts pulling two hibernate-core versions (starter BOM plus explicit version); shaded assemblies duplicating META-INF/services lines; adding a custom schema management tool without excluding/consolidating the default registration; upgrading Hibernate where the artifact coordinates changed and both old and new jars remain.

Related errors

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