Your application stops during startup and prints APPLICATION FAILED TO START. The report names a DataSource problem. This guide lists the causes from most to least likely. Each one has a fix and a way to check that it worked.
The guide also covers the other startup failure beginners meet first: port 8080 already in use.
The instructions follow the official Spring Boot reference pages for SQL databases, SpringApplication and the how-to guides. The startup log in those pages shows Java 25.0.4. Check the reference page for your own Spring Boot version if a property name differs.
The symptom: what you see and why
When startup fails, Spring Boot runs its registered FailureAnalyzer beans. They print a short report with two parts:
***************************
APPLICATION FAILED TO START
***************************
Description:
...
Action:
...
Description says what went wrong. Action says what to do. Read both before you change anything. The Action line is often the whole fix.
For a DataSource error, the reason is usually this. Spring Boot needs a database connection. If you set no spring.datasource.url, it tries to auto-configure an embedded database instead. If it finds no embedded database on the classpath, startup fails.
The exact wording of the message can vary between versions, so match on the Description and Action text on your screen, not on this guide.
Step 0: get more detail before you guess
If the report is not enough, print the full conditions report. It lists every auto-configuration decision Spring Boot made. Run your jar with the --debug flag:
This works because the debug property turns on the ConditionEvaluationReport output. You can also pass -Ddebug as a system property.
Look for the DataSource-related entries. They show which conditions matched and which did not.
java -jar myproject-0.0.1-SNAPSHOT.jar --debug
Cause 1 (most likely): no URL is set and no embedded database is available
The reference page says you should at least set spring.datasource.url. Otherwise Spring Boot tries to auto-configure an embedded database.
You have two ways out. Pick the one that matches your goal.
Fix A: you want a real database
Set the connection properties in application.properties. Use your own values in place of the placeholders. This gives Spring Boot a URL, so it stops looking for an embedded database.
Spring Boot deduces the JDBC driver class from the URL for most databases. You also need your database's JDBC driver on the classpath. The driver's coordinates come from its vendor, so check the vendor's documentation.
Fix B: you want an in-memory database for development
Add an embedded database dependency. Spring Boot can auto-configure embedded H2, HSQL and Derby (deprecated), and you need no connection URL. The reference page shows this Maven example with HSQLDB. Add it to pom.xml so an embedded database exists on the classpath.
Remember that in-memory data is lost when the app ends. You must populate it at startup.
Confirm it worked: restart the app. The DataSource report must be gone, and the log must end with a Started ... in ... seconds line.
spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=YOUR_DB_PASSWORD
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.hsqldb</groupId>
<artifactId>hsqldb</artifactId>
<scope>runtime</scope>
</dependency>
Cause 2: spring-jdbc is missing from the classpath
An embedded database is only auto-configured if spring-jdbc is present. In the HSQLDB example above, spring-boot-starter-data-jpa pulls it in for you.
If you added only the database jar and no starter that includes spring-jdbc, nothing configures the DataSource.
Fix: add a starter that brings in spring-jdbc, such as spring-boot-starter-data-jpa in the example above. This gives auto-configuration the class it needs.
Confirm it worked: restart with --debug and check the DataSource conditions in the report. The embedded database entry should now match.
Cause 3: the driver class cannot be loaded
For a pooling DataSource, Spring Boot checks that a valid Driver class is available before it does anything else. If you set spring.datasource.driver-class-name, that class must be loadable.
The reference page gives this case: spring.datasource.driver-class-name=com.mysql.jdbc.Driver only works if that class is on the classpath.
Fix, in order:
- Remove
spring.datasource.driver-class-name. Spring Boot can deduce the driver from the URL for most databases, so you rarely need it. - If you must keep it, check the spelling of the class name. A typo cannot be loaded.
- Make sure the JDBC driver dependency is in your build file. A class name with no jar behind it cannot be loaded either.
Confirm it worked: the app starts and the report no longer mentions the driver class.
Cause 4: more than one embedded database is on the classpath
If several embedded databases are on the classpath, Spring Boot needs to know which to use. Set spring.datasource.embedded-database-connection to choose one.
Setting it to none disables auto-configuration of an embedded database. Use that only when you supply a real URL or your own DataSource.
The documentation lists the property but not each accepted value, so check the Spring Boot reference page for the values your version allows.
Fix: remove the embedded database you do not need from your build file. This is the simplest option, because only one database remains.
Confirm it worked: the app starts, and the log shows no ambiguity about the database.
Cause 5: your own DataSource bean is not bound correctly
If you define a DataSource @Bean, Spring Boot reuses it everywhere a DataSource is needed. Your properties must then use the prefix you bind, not spring.datasource.*.
In the how-to example the prefix is app.datasource. The builder detects the pool from the classpath and the driver from the JDBC URL.
Fix: match the prefix in @ConfigurationProperties to the prefix in your properties file. This binds your values to the bean.
Confirm it worked: restart the app. Spring Boot finds your bean and the failure disappears.
import javax.sql.DataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.jdbc.DataSourceBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class MyDataSourceConfiguration {
@Bean
@ConfigurationProperties("app.datasource")
public DataSource dataSource() {
return DataSourceBuilder.create().build();
}
}
app.datasource.url=jdbc:mysql://localhost/test
app.datasource.username=dbuser
app.datasource.password=YOUR_DB_PASSWORD
app.datasource.pool-size=30
Another common startup error: port 8080 already in use
If another process already listens on port 8080, the report reads like this:
Embedded servlet container failed to start. Port 8080 was already in use.
Action:
Identify and stop the process that is listening on port 8080 or configure this application to listen on another port.
You have two fixes.
Stop the other process. This frees the port the app wants.
Change the port. Set server.port in application.properties, or use the SERVER_PORT OS environment variable. Relaxed binding maps one to the other. Use server.port=0 to let the OS pick a free port.
If you do not want a web server at all, set spring.main.web-application-type=none.
Confirm it worked: the log shows Tomcat started on port 8081 (http) or the port you chose.
server.port=8081
When none of these match
If the report is unclear, use the tools Spring Boot gives you:
- Run with
--debugor-Ddebugto log all auto-configuration decisions. - Add
spring-boot-actuatorand open/actuator/conditionson a running app. It shows the same report as JSON. - Open the
configpropsendpoint to see the available configuration properties.
These show what Spring Boot added and what it skipped, so you can see why the DataSource was not configured.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| The app still fails after you add spring.datasource.url | The JDBC driver is not on the classpath, or spring.datasource.driver-class-name names a class that cannot be loaded. | Add your database's JDBC driver dependency and remove spring.datasource.driver-class-name unless you need it. |
| The embedded database is not auto-configured even though its jar is present | spring-jdbc is not on the classpath. | Add a starter that brings in spring-jdbc, such as spring-boot-starter-data-jpa. |
| More than one embedded database is found | Several embedded database jars are on the classpath. | Remove the one you do not need, or set spring.datasource.embedded-database-connection. |
| Port 8080 was already in use | Another process listens on the port. | Stop that process, or set server.port (or SERVER_PORT) to another value. |
| The failure report does not explain the problem | No FailureAnalyzer handled the exception. | Start with --debug to print the conditions report. |
Frequently asked questions
Why does Spring Boot look for an embedded database when I did not ask for one?
If you do not set spring.datasource.url, Spring Boot tries to auto-configure an embedded database. If none is on the classpath, startup fails.
Do I have to set spring.datasource.driver-class-name?
No. Spring Boot can deduce the driver class from the URL for most databases. If you set it, the class must be loadable.
How do I turn off embedded database auto-configuration?
Set spring.datasource.embedded-database-connection to none.
How do I see why auto-configuration did not apply?
Start the app with --debug or -Ddebug, or use the /actuator/conditions endpoint if you use spring-boot-actuator.
How do I pick a different HTTP port?
Set server.port in application.properties or the SERVER_PORT environment variable. Use server.port=0 for a random free port.
References
From Grokem: https://www.grokem.com/programming/web-development/backend/fix-failed-to-configure-a-datasource-in-spring-boot-causes-and-fixes-for-beginners









