Skip to content
javahacks.dev
Spring Boot

Fix Spring Boot Failed to Configure a DataSource Error

Fix the Spring Boot DataSource startup failure by checking the URL, the driver, the active profile and whether the application should have a database at all.

5 min read
Summarize in AI
Flat illustration of an application reaching a database through a JDBC driver, with the Spring Boot, Hibernate, Flyway and MariaDB logos.

The report appears before the first request, and it looks like this:

Text
***************************
APPLICATION FAILED TO START
***************************

Description:

Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.

Reason: Failed to determine a suitable driver class

Action:

Consider the following:
	If you want an embedded database (H2, HSQL or Derby), please put it on the classpath.
	If you have database settings to be loaded from a particular profile you may need to activate it (no profiles are currently active).

Spring Boot found spring-boot-starter-data-jpa or a JDBC starter, tried to build a DataSource and had no URL. The causes are short, and the order below goes from the most common. The setup this belongs to is in Spring Boot from first project to production.

Cause 1: the URL is not set

Check that the property exists where Spring Boot looks:

src/main/resources/application.propertiesproperties
spring.datasource.url=jdbc:postgresql://localhost:5432/shop
spring.datasource.username=shop
spring.datasource.password=change-me

Typos are the usual reason: spring.datasource.jdbc-url is a HikariCP property used when you define your own DataSource bean, and spring.datasource.url is the one auto-configuration reads.

Cause 2: the profile that holds the URL is not active

The message says "no profiles are currently active" for a reason. If your URL lives in application-prod.yaml, nothing reads it until you run with --spring.profiles.active=prod or set SPRING_PROFILES_ACTIVE=prod. Print what is active at startup: the first log lines say The following 1 profile is active: "prod" or No active profile set, falling back to 1 default profile: "default".

Cause 3: a test resource shadows your main configuration

If src/test/resources/application.properties exists, it replaces the main file on the test classpath rather than adding to it. A test that fails with this message while the app runs fine is usually this. Put test-only overrides in application-test.properties with @ActiveProfiles("test"), or use Testcontainers with @ServiceConnection so no URL is needed, as in a practical testing strategy.

Cause 4: the environment variable is spelled wrong

Relaxed binding maps SPRING_DATASOURCE_URL to spring.datasource.url. It does not map DATASOURCE_URL or SPRING_DATASOURCE_JDBC_URL. In Kubernetes and Docker, an unset variable that you reference as ${DB_URL} in the file turns into a different error.

Cause 5: the driver is missing

With a URL but no driver on the classpath, the reason line changes to Failed to determine a suitable driver class or the connection fails with a different exception. Add the driver, for PostgreSQL org.postgresql:postgresql with runtime scope. If the failure is a connection problem rather than a configuration one, see connection refused on port 5432.

When there should be no database

Some applications pull in JPA transitively and do not need a database, for example a command-line tool built from a shared module. Remove the starter, or exclude the auto-configuration:

properties
spring.autoconfigure.exclude=org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration

The package of that class moved when Spring Boot 4 split auto-configuration into modules, so let your IDE complete the name for the version you use. Excluding it hides the symptom, so do it only when you are sure.

Test the connection outside Spring

When the URL looks right and the failure continues, separate Spring from the database. A plain JDBC connection answers whether the URL, the driver and the credentials work at all:

java
try (Connection c = DriverManager.getConnection(url, user, password)) {
    System.out.println(c.getMetaData().getDatabaseProductName());
}

Run it from a scratch class with the same classpath as the application. A No suitable driver message means the driver jar is absent or the URL prefix is wrong, and a Communications link failure or Connection refused means the database is not reachable from where the code runs. In a container, localhost is the container itself, so a URL that works on a laptop points nowhere in the cluster.

The URL formats that are easy to get wrong

DatabaseURL shapeCommon mistake
PostgreSQLjdbc:postgresql://host:5432/shopMissing jdbc: prefix, or postgres:// copied from a connection string
MySQLjdbc:mysql://host:3306/shopUsing mariadb driver with a mysql URL
SQL Serverjdbc:sqlserver://host:1433;databaseName=shopA slash and not a semicolon before the database name
H2 in memoryjdbc:h2:mem:testdbThe H2 jar is test scope, so it vanishes at runtime
Oraclejdbc:oracle:thin:@//host:1521/serviceUsing a SID where a service name is needed

A hosted database often gives a URL starting with postgres:// or postgresql://user:pass@host/db. That is not a JDBC URL. Split it into spring.datasource.url, username and password.

Read the conditions report

When nothing in the configuration looks wrong, ask Boot why it did not configure a data source. The report names the condition that failed:

Shell
java -jar app.jar --debug 2>&1 | grep -A6 'DataSourceAutoConfiguration'

The negative matches section says, for example, DataSourceAutoConfiguration did not match: @ConditionalOnClass did not find required class 'javax.sql.DataSource', or no embedded database. This line says whether the class is on the classpath and whether a URL was seen. It saves guessing between a missing property and a missing dependency.

A dependency that pulls in a database requirement

spring-boot-starter-data-jpa, spring-boot-starter-jdbc and spring-boot-starter-batch all expect a data source. A project that adds one of them for a minor reason, such as a shared library, gets this error without ever using a database. Search the dependency tree for the starter that brought the requirement in:

Shell
./mvnw dependency:tree | grep -E 'starter-(jdbc|data-jpa|batch)'

If the application needs no database, remove the starter. If it needs the starter for a library but not the database, exclude the auto-configuration:

properties
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

Use the exclusion rarely. A service that excludes the data source to start and then fails on the first query has only moved the error.

Local services that are not running

A Compose file starts the database, and the application starts first and fails because the port is not open yet. Use a health check and make the application wait, or let Spring Boot's Docker Compose support manage the order, as described in Docker Compose support. The symptom differs from this post's error, with a connection refused after the URL was read, and the cause is the same class of mistake: the configuration is fine and the environment around it is not ready.

What this does not cover

This report is about configuration. If the pool starts and then requests fail, you have a connection pool timeout, not a missing DataSource. The Spring Boot data access reference lists every spring.datasource.* property and how the pool is selected. The Spring Boot how-to guides documents the behavior in detail.

Also inHibernate
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.