Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Spring Boot: Failed to configure a DataSource and no url attribute

The application never reached the database. The URL is missing, in the wrong file, or under a profile that is not active.

~5 min readJava
#Spring Boot#Java#JDBC#Configuration
A Spring Boot jar with an empty database socket and an amber missing url plate beside a cyan properties sheet

Introduction & Quick Summary

A Spring Boot application starts and then fails:

code
*************************** 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

Nothing is wrong with the database: the application never got far enough to connect. Spring Boot's auto-configuration found spring-jdbc or spring-data-jpa on the classpath, looked for spring.datasource.url, found neither a URL nor an embedded database such as H2, and stopped.

The three causes worth checking first:

  1. The properties are not where Boot reads them. A application.properties in src/main/resources is on the classpath; the same file next to pom.xml is not. A YAML file with tabs instead of spaces is silently skipped.
  2. The profile is not active. spring.datasource.url lives in application-prod.yml, and the app started without SPRING_PROFILES_ACTIVE=prod.
  3. The dependency is not what you think. The driver is missing (so no url can be used even if present), or a test-scoped H2 was removed, and the app is now running a Jar that expects a real database.

If the goal is a small service that should not need a database at all, the fourth answer is to exclude the auto-configuration instead of adding a fake URL.

Core Mechanics, Signatures & Reproducible Setup

DataSourceAutoConfiguration is conditional: it activates when a DataSource class is on the classpath and no DataSource bean is defined. It then needs one of two things - an embedded database it can create (H2, HSQLDB, Derby) or an explicit spring.datasource.url (or spring.datasource.jdbc-url for a pooled vendor config). If it has neither, it fails during context refresh with the message above.

properties
# src/main/resources/application.properties spring.datasource.url=jdbc:postgresql://localhost:5432/app spring.datasource.username=app spring.datasource.password=${DB_PASSWORD} spring.datasource.driver-class-name=org.postgresql.Driver spring.datasource.hikari.maximum-pool-size=10 spring.jpa.hibernate.ddl-auto=validate
# or application.yml - spaces only, no tabs spring: datasource: url: jdbc:postgresql://localhost:5432/app username: app password: ${DB_PASSWORD}
xml
<!-- the driver must be present at runtime, not only in a test scope --> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <scope>runtime</scope> </dependency>

Reproduce it in ten seconds by removing the URL from the properties and starting the app; the stack trace ends in DataSourceProperties.determineUrl, which is the exact line to look for when the message differs slightly between versions.

Key Comparison Table

SituationWhat Boot seesResultFix
No URL, no embedded DBjdbc on classpaththis errorset the url or exclude
URL present, driver missingurl but no driver classCannot load driver classadd the driver dependency
Properties file off the classpathnothingthis errormove to src/main/resources
Profile-specific file, profile offno urlthis erroractivate the profile
URL in spring.datasource.hikari.jdbc-urlpooled config onlythis erroruse spring.datasource.url
Multi-datasource beansauto-config backed offmay still fail on first usedefine the bean explicitly
FixWhen it is rightWhen it is wrong
Set spring.datasource.urlthe app must use a databasethe app has no persistence
Add H2 with test scopetests onlyproduction startup
Exclude DataSourceAutoConfigurationa library app with no DBanything that uses JPA
Provide a DataSource beanmultiple databasesone database with defaults
spring.autoconfigure.excludetuning specific auto-configshiding a real misconfiguration

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Properties are loaded from the classpath, not the working directory

Spring Boot reads application.properties and application.yml from the classpath root, then from ./config/, then from the working directory as a last resort. A file in src/main/resources ends up in target/classes or build/resources/main; a file at the project root does not. Confirm what the running jar actually contains:

bash
jar tf build/libs/app.jar | grep -E 'application.*(properties|yml)' unzip -p build/libs/app.jar BOOT-INF/classes/application.yml | head -20

In an IDE the working directory is often the module root, which is why a misplaced file "works" locally and fails once packaged.

2. YAML syntax that silently drops a block

A tab character, a duplicate spring: key, or a document separator in the wrong place makes SnakeYAML skip or override the datasource block. Boot reports the same "url not specified" error with no parse error when the file is valid YAML but the block is nested under the wrong key:

spring: datasource: url: jdbc:mysql://db:3306/app?useSSL=false --- spring: config: activate: on-profile: prod datasource: url: jdbc:mysql://prod-db:3306/app

Paste a suspect file into YAML Formatter to see the parsed structure; a spring key appearing twice means the second one replaced the first rather than merging.

3. Profiles and environment overrides

application-prod.yml does nothing unless the prod profile is active, and environment variables beat files. Check the effective values rather than the file:

bash
java -jar app.jar --debug 2>&1 | grep -A5 'DataSourceAutoConfiguration' SPRING_PROFILES_ACTIVE=prod java -jar app.jar
java
@SpringBootApplication public class App { public static void main(String[] args) { var ctx = SpringApplication.run(App.class, args); System.out.println(ctx.getEnvironment().getProperty("spring.datasource.url")); } }

Printing the resolved property once at startup is the shortest path from "it should be set" to knowing whether it is.

4. A missing driver produces the same headline

If the URL is present but the driver class is not on the runtime classpath, the message is Failed to load driver class org.postgresql.Driver - different text, same failed start. A driver declared with <scope>test</scope> disappears from the packaged jar; a driver excluded by a dependency's exclusions disappears the same way:

bash
mvn dependency:tree -Dincludes=org.postgresql:postgresql ./gradlew dependencies --configuration runtimeClasspath | grep -i postgres

Set spring.datasource.driver-class-name explicitly only when Boot cannot infer it from the URL; an explicit name that is wrong is worse than none.

5. Tests that need no database

A @SpringBootTest without a URL fails the same way. Either give the test an embedded database or slice away the persistence layer:

java
@SpringBootTest(properties = { "spring.datasource.url=jdbc:h2:mem:testdb", "spring.jpa.hibernate.ddl-auto=create-drop" }) class ServiceIT {}
java
@WebMvcTest(OrderController.class) // no DataSource auto-config at all class OrderControllerTest {}

Prefer the slice when the test does not touch SQL; it starts faster and cannot fail because of a database URL.

6. Multiple datasources and the auto-config backoff

Once you define your own DataSource bean, the auto-configuration backs off and the error changes to whatever your bean does. Mark the primary one, or Boot injects by type and fails with a different message:

java
@Configuration class DataSourceConfig { @Primary @Bean @ConfigurationProperties("app.primary.datasource") DataSource primary() { return DataSourceBuilder.create().build(); } @Bean @ConfigurationProperties("app.reporting.datasource") DataSource reporting() { return DataSourceBuilder.create().build(); } }

@ConfigurationProperties binds url, username and password from the prefix, which is why the app.primary.datasource.url key has to exist even though spring.datasource.url is set.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Adding H2 to the main classpath to silence the error. The app then starts with an empty in-memory database and silently ignores the real one.
  • spring.datasource.jdbc-url in a plain Boot app. That key belongs to a manually built pooled DataSource; Boot reads spring.datasource.url.
  • Environment variable naming. SPRING_DATASOURCE_URL maps to spring.datasource.url, but SPRING_DATASOURCE_JDBCURL does not map to jdbc-url; relaxed binding only handles case and separators, not invented names.
  • A profile file named application-dev.yml but activated as development. The suffix must match the profile name exactly.
  • Spring Boot 3 versus 2 property names. spring.datasource.initialization-mode is gone in 3.x, and spring.sql.init.* replaced it; a leftover key is ignored without an error.
  • Native images. A driver that relies on reflection needs a hint; the build succeeds and the runtime fails with the same "no suitable driver" text.
  • Excluding DataSourceAutoConfiguration while using JPA. The repository layer then fails later with a missing EntityManagerFactory, which is a harder error to read.

Primary references: SQL databases in Spring Boot documents the datasource properties and the auto-configuration conditions, and Spring Boot's data access how-to covers configuring a single or multiple datasources by hand.

Official references

primary documentation

The Java documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.