Introduction

This error usually means Spring Boot tried to evaluate JDBC JNDI auto-configuration and ran into missing environment assumptions. The real fix is rarely in the IllegalStateException line itself; it is usually in the nested cause, which often points to a missing JNDI name, an unavailable servlet container resource, or a classpath mismatch.

What Spring Boot Is Trying to Do

JndiDataSourceAutoConfiguration is one of Spring Boot's optional auto-configurations. It becomes relevant when Boot thinks your application wants to obtain a DataSource from JNDI rather than building one directly from URL, username, and password properties.

That path is common in application servers such as Tomcat, WildFly, or WebLogic, where the database connection is managed by the container.

A typical JNDI-based property looks like this:

spring.datasource.jndi-name=java:comp/env/jdbc/AppDb

If Boot sees a setup like that but the environment does not actually provide the JNDI resource, startup can fail while processing the condition.

Read the Nested Cause, Not Just the Top Exception

The top-level IllegalStateException is usually a wrapper. The useful information is normally further down the stack trace.

Common underlying causes include:

• 'spring.datasource.jndi-name is set incorrectly'
• the application is running outside a container that provides JNDI
• the expected JNDI resource is missing in the target environment
• dependency or classpath issues make the condition evaluation fail

So the first diagnostic step is to read the Caused by chain carefully rather than stopping at the top exception line.

The Most Common Misconfiguration

A very common failure pattern is keeping a JNDI datasource property in application.properties while running locally with java -jar or in an environment that does not expose the JNDI resource.

If you are not actually using container-managed JNDI, remove that property and configure the datasource directly.

spring.datasource.url=jdbc:postgresql://localhost:5432/app
spring.datasource.username=app
spring.datasource.password=secret

That often resolves the issue immediately because Boot no longer tries to go through JNDI.

If JNDI Is Intentional, Verify the Environment

If the application is supposed to use JNDI, then the container must actually expose the named datasource.

For example, embedded local startup and container deployment are not equivalent. A property that works inside a full application server may fail in a plain local Spring Boot process because no JNDI context exists there.

In that case, profile-specific configuration is often the cleanest answer:

1# application-prod.properties
2spring.datasource.jndi-name=java:comp/env/jdbc/AppDb
3
4# application-local.properties
5spring.datasource.url=jdbc:postgresql://localhost:5432/app
6spring.datasource.username=app
7spring.datasource.password=secret

This keeps the local and deployed environments honest instead of pretending they provide the same infrastructure.

Excluding the Auto-Configuration Is Sometimes Correct

If the application should never use JNDI in the current deployment model, you can exclude that auto-configuration explicitly.

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3import org.springframework.boot.autoconfigure.jdbc.JndiDataSourceAutoConfiguration;
4
5@SpringBootApplication(exclude = JndiDataSourceAutoConfiguration.class)
6public class App {
7    public static void main(String[] args) {
8        SpringApplication.run(App.class, args);
9    }
10}

This is a good option when the presence of JNDI-related classes or properties causes Spring Boot to explore a configuration path you do not want at all.

Use the Condition Report When the Cause Is Unclear

Spring Boot's condition evaluation report can help when it is not obvious why the auto-configuration path was activated.

debug=true

Or run with a debug flag:

java -jar app.jar --debug

This makes it easier to see which conditions matched and why Boot tried to process JndiDataSourceAutoConfiguration in the first place.

Common Pitfalls

The most common mistake is focusing on the wrapper IllegalStateException and ignoring the nested cause that actually explains the failure.

Another common issue is leaving a JNDI datasource property enabled in environments that do not provide JNDI resources. Developers also often assume that local bootstrapping with java -jar behaves like a full application server deployment, even though the infrastructure is different.

Summary

• This error usually means Spring Boot tried to evaluate JNDI datasource auto-configuration under the wrong assumptions.
• Read the nested Caused by section carefully.
• Remove spring.datasource.jndi-name if the app should use a direct JDBC datasource instead.
• If JNDI is intentional, verify that the target container actually exposes the resource.
• Use profile-specific config or explicit auto-configuration exclusion when environments differ.