Skip to content

Grokem · https://www.grokem.com/programming/web-development/backend/fix-failed-to-configure-a-datasource-in-spring-boot-causes-and-fixes-for-beginners

BackendTroubleshooting guide

Fix 'Failed to configure a DataSource' in Spring Boot: Causes and Fixes for Beginners

Your Spring Boot app stops at startup with a DataSource error. Work through the likely causes in order, apply the fix for each, and confirm the app starts, including the port 8080 error.

Krishna Sharma

Technical Writer

Published
  • 8 min read
  • 0 sec

Tested with
  • Java25.0.4
  • Spring Boot
  • Maven
Your progress
  1. Fix 'Failed to configure a DataSource' in Spring Boot: Causes and Fixes for Beginners8 min(finished)
    0%

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.

Spring Boot startsspring.datasource.urlset?embedded database andspring-jdbc on classpath?pooled DataSourcedriver class must loadembedded databaseconfiguredAPPLICATION FAILEDTO STARTNoYesYesNo
How Spring Boot decides between a configured URL, an embedded database and a startup failure.

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.

bash
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.

properties
spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=YOUR_DB_PASSWORD
xml
<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:

  1. Remove spring.datasource.driver-class-name. Spring Boot can deduce the driver from the URL for most databases, so you rarely need it.
  2. If you must keep it, check the spelling of the class name. A typo cannot be loaded.
  3. 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.

java
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();
    }

}
properties
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.

properties
server.port=8081

When none of these match

If the report is unclear, use the tools Spring Boot gives you:

  • Run with --debug or -Ddebug to log all auto-configuration decisions.
  • Add spring-boot-actuator and open /actuator/conditions on a running app. It shows the same report as JSON.
  • Open the configprops endpoint 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

ProblemLikely causeFix
The app still fails after you add spring.datasource.urlThe 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 presentspring-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 foundSeveral 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 useAnother 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 problemNo 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

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Backend

From the community

Learning paths

Learning pathBeginner

Infrastructure basics for data work

The ground a data project stands on: the command line, how a name finds a server, packaging an app in a container, where files and databases live, keeping secrets out of code, backups you have tested and a cloud bill you control.

7 lessonsabout 15 minStart

Learning pathIntermediate

SQL for data work

From removing duplicates and window functions to modelling for reporting, cohort analysis, indexes and query plans: the SQL a working analyst or engineer uses every week, each lesson with queries that were run.

8 lessonsabout 90 minStart

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.