hibernate/hibernate-orm · critical · HibernateException

JNDI name [{}] could not be resolved

Error message

JNDI name [{}] could not be resolved

What it means

The JNDI name configured in hibernate.connection.datasource was handed to JndiService.locate() and the lookup returned null, meaning nothing is bound at that name in the reachable JNDI tree. Hibernate throws this immediately at bootstrap because the multi-tenant provider has no root object to derive per-tenant DataSources from.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/DataSourceBasedMultiTenantConnectionProviderImpl.java:88

	}

	@Override
	public void injectServices(@Nonnull ServiceRegistryImplementor serviceRegistry) {
		final var configurationService = serviceRegistry.requireService( ConfigurationService.class );
		final Object dataSourceConfigValue = configurationService.getSettings().get( DATASOURCE );
		if ( !(dataSourceConfigValue instanceof String configuredJndiName) ) {
			throw new HibernateException( "illegal value for configuration setting '" + DATASOURCE + "'" );
		}
		jndiName = configuredJndiName;

		jndiService = serviceRegistry.getService( JndiService.class );
		if ( jndiService == null ) {
			throw new HibernateException( "Could not locate JndiService from DataSourceBasedMultiTenantConnectionProviderImpl" );
		}

		final Object namedObject = jndiService.locate( this.jndiName );
		if ( namedObject == null ) {
			throw new HibernateException( "JNDI name [" + this.jndiName + "] could not be resolved" );
		}
		else if ( namedObject instanceof DataSource datasource ) {
			final int loc = jndiName.lastIndexOf( '/' );
			baseJndiNamespace = jndiName.substring( 0, loc );
			final String prefix = jndiName.substring( loc + 1);
			tenantIdentifierForAny = (T) prefix;
			dataSourceMap().put( tenantIdentifierForAny, datasource );
		}
		else if ( namedObject instanceof Context ) {
			baseJndiNamespace = jndiName;
			final Object configuredTenantId =
					configurationService.getSettings().get( TENANT_IDENTIFIER_TO_USE_FOR_ANY_KEY );
			tenantIdentifierForAny = (T) configuredTenantId;
			if ( tenantIdentifierForAny == null ) {
				throw new HibernateException( "JNDI name named a Context, but tenant identifier to use for ANY was not specified" );
			}
		}
		else {

View on GitHub (pinned to fad1729dce)

Solutions

1. Pre-verify the binding with a direct lookup: new InitialContext().lookup("<name>") and fix the configured value to the exact bound name
2. Check the server's datasource definition (subsystem=datasources, server.xml Resource, etc.) and deploy/bind the resource
3. Align hibernate.jndi.* environment properties with the actual naming provider (local vs remote InitialContext)

Example fix

// before
<property name="hibernate.connection.datasource" value="java:/datasources/tenantRoot"/> <!-- not bound -->

// after (name matches the actual WildFly binding)
<property name="hibernate.connection.datasource" value="java:jboss/datasources/tenantRoot"/>

// pre-flight the exact binding before Hibernate boots
Object bound;
try {
    bound = new InitialContext().lookup(jndiName);
} catch (NamingException e) {
    throw new IllegalStateException("Nothing bound at " + jndiName, e);
}
if ( bound == null ) throw new IllegalStateException("JNDI returned null for " + jndiName);

When it happens

Trigger: jndiService.locate(jndiName) returns null - name typo (java:/datasources/tenants vs java:datasources/tenants), the DataSource not deployed/bound, looking up in the wrong namespace, or JNDI environment pointing at the wrong InitialContext (remote vs local).

Common situations: DataSource defined in the app server but under a different JNDI name than configured; WildFly/Jetty/TomEE binding names that differ between versions (java:jboss/datasources/... vs java:/comp/env/...); integration tests with an empty embedded JNDI tree.

Related errors

• illegal value for configuration setting 'hibernate.connectio
• Could not locate JndiService from DataSourceBasedMultiTenant
• Unknown object type [{}] found in JNDI location [{}]
• JNDI name named a Context, but tenant identifier to use for
• Unable to access TransactionManager or UserTransaction to ma

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