hibernate/hibernate-orm · error · UnknownServiceException

Unknown service requested [${serviceRole.getName()}]

Error message

Unknown service requested [${serviceRole.getName()}]

What it means

Inside getService(role), after taking the init lock, Hibernate looks up the ServiceBinding for the role; if no initiator or explicit registration ever created a binding for it, UnknownServiceException("Unknown service requested [...]") is thrown. This is the runtime twin of the requireService path: the role is genuinely unknown to this registry (and not reachable through parent crawling).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/service/internal/AbstractServiceRegistryImpl.java:209

			return parent.getService( serviceRole );
		}
		// TODO: should an exception be thrown if active == false???
		R service = serviceRole.cast( initializedServiceByRole.get( serviceRole ) );
		if ( service != null ) {
			return service;
		}

		//Any service initialization needs synchronization
		synchronized ( this ) {
			// Check again after having acquired the lock:
			service = serviceRole.cast( initializedServiceByRole.get( serviceRole ) );
			if ( service != null ) {
				return service;
			}

			final ServiceBinding<R> serviceBinding = locateServiceBinding( serviceRole );
			if ( serviceBinding == null ) {
				throw new UnknownServiceException( serviceRole );
			}
			service = serviceBinding.getService();
			if ( service == null ) {
				service = initializeService( serviceBinding );
			}
			if ( service != null ) {
				// add the service only after it is completely initialized
				initializedServiceByRole.put( serviceRole, service );
			}
			return service;
		}
	}

	protected <R extends Service> void registerService(@Nonnull ServiceBinding<R> serviceBinding, R service) {
		serviceBinding.setService( service );
		synchronized ( serviceBindingList ) {
			serviceBindingList.add( serviceBinding );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the role is registered: add a StandardServiceInitiator or ServiceContributor for it, or builder.addService(role, instance)
2. Check the Hibernate version's service list — the role may have been renamed/merged in the upgrade
3. Request from the correct registry in the hierarchy rather than an arbitrary one
4. Guard optional lookups with getService(role) == null instead of requireService

Example fix

// before
final ConnectionProvider cp = registryService.getService(ConnectionProvider.class); // ok
final MyService s = registryService.requireService(MyService.class); // UnknownServiceException

// after
// register the custom role before first use
public class MyServiceInitiator implements StandardServiceInitiator<MyService> {
    public Class<MyService> getServiceInitiated() { return MyService.class; }
    public MyService initiateService(ConfigurationValues configurationValues, ServiceRegistryImplementor registry) {
        return new MyServiceImpl();
    }
}
// + META-INF/services/org.hibernate.servicecontributor listing the contributor

MyService service = registry.getService(MyService.class);
if (service == null) {
    service = new MyServiceDefault();
    // or: ((StandardServiceRegistryBuilder) builder).addService(MyService.class, service);
}

boolean isRoleBound(StandardServiceRegistry registry, Class<? extends Service> role) {
    return registry.getService(role) != null; // null == unknown/unbound
}

try {
    return registry.requireService(role);
}
catch (UnknownServiceException e) {
    // role never registered here; register or degrade gracefully
    LOG.warn("unknown service {} — not registered", role.getName());
    return null;
}

When it happens

Trigger: Requesting a service role with no registered binding; roles removed, renamed, or merged between Hibernate versions (notably 5.x to 6.x); a registry that was already destroyed; custom integrations assuming an internal service still exists.

Common situations: Upgrading Hibernate where internal service classes moved packages or were replaced; third-party dialects or integrations looking up version-specific services; services registered on a sibling registry rather than the requested one.

Related errors

• Bootstrap registry should only contain provided services
• No ServiceRegistry was passed to Configuration#buildSessionF
• Could not locate JndiService from DataSourceBasedMultiTenant
• Unknown service requested [${serviceRole.getName()}]
• ServiceRegistry parent needs to implement ServiceRegistryImp

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