hibernate/hibernate-orm · error · ServiceDependencyException

Dependency [${dependentServiceRole}] declared by service [${

Error message

Dependency [${dependentServiceRole}] declared by service [${service}] not found

What it means

While wiring a service, Hibernate reflectively invokes methods annotated with @InjectService. When the dependent role cannot be resolved (getService returned null) and the annotation declares required = true (the default), ServiceDependencyException is thrown naming both the missing dependency role and the dependent service. The registry cannot finish initializing that service.

Source

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

	private <T extends Service> void processInjection(
			@Nonnull T service,
			@Nonnull Method injectionMethod,
			@Nonnull InjectService injectService) {
		injectDependentService( service, injectionMethod, injectService,
				dependentServiceRole( injectionMethod, injectService ) );
	}

	private <T extends Service> void injectDependentService(
			@Nonnull T service,
			@Nonnull Method injectionMethod,
			@Nonnull InjectService injectService,
			@Nonnull Class<? extends Service> dependentServiceRole) {
		// todo : because of the use of proxies, this is no longer returning null here...

		final var dependantService = getService( dependentServiceRole );
		if ( dependantService == null ) {
			if ( injectService.required() ) {
				throw new ServiceDependencyException(
						"Dependency [" + dependentServiceRole + "] declared by service [" + service + "] not found"
				);
			}
		}
		else {
			try {
				injectionMethod.invoke( service, dependantService );
			}
			catch ( Exception e ) {
				throw new ServiceDependencyException( "Cannot inject dependency service", e );
			}
		}
	}

	private static Class<? extends Service> dependentServiceRole(
			@Nonnull Method injectionMethod,
			@Nonnull InjectService injectService) {
		final var parameterTypes = injectionMethod.getParameterTypes();

View on GitHub (pinned to fad1729dce)

Solutions

1. Register the missing dependency role (initiator/contributor/addService) before the dependent service initializes
2. If the dependency is genuinely optional, annotate the setter with @InjectService(required = false) and null-check inside
3. Verify the serviceRole attribute and the setter parameter type match the registered role exactly
4. For tests, build the registry with the real services the code-under-test depends on instead of a stripped-down one

Example fix

// before
@InjectService // required=true by default, role not registered
public void setMetrics(MetricsService metrics) { this.metrics = metrics; }

// after
@InjectService(required = false)
public void setMetrics(MetricsService metrics) { this.metrics = metrics; }
// ...and at use site:
if (metrics != null) metrics.record();

// before initializing the dependent service, confirm the role is bound
if (registry.getService(TheDependency.class) == null) {
    builder.addService(TheDependency.class, new TheDependencyImpl());
}

try {
    registry.requireService(MyDependentService.class);
}
catch (ServiceDependencyException e) {
    // message names the missing role; register it and retry the lookup
    LOG.error("missing service dependency: {}", e.getMessage());
}

When it happens

Trigger: A custom or internal service declaring a required @InjectService dependency on a role that is not registered in the same registry hierarchy; init-order or hierarchy problems where the dependency lives in a sibling registry; role class renamed between Hibernate versions.

Common situations: Custom services depending on optional Hibernate services that were never contributed; test registries built with a subset of services; integrations written against one Hibernate version running against another where the dependency role moved.

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/180bb0db29806af7. Report an issue: GitHub.