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.

Introduction & Quick Summary
A Spring Boot application starts and then fails:
***************************
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 classNothing 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:
- The properties are not where Boot reads them. A
application.propertiesinsrc/main/resourcesis on the classpath; the same file next topom.xmlis not. A YAML file with tabs instead of spaces is silently skipped. - The profile is not active.
spring.datasource.urllives inapplication-prod.yml, and the app started withoutSPRING_PROFILES_ACTIVE=prod. - The dependency is not what you think. The driver is missing (so no
urlcan 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.
# 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}<!-- 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
| Situation | What Boot sees | Result | Fix |
|---|---|---|---|
| No URL, no embedded DB | jdbc on classpath | this error | set the url or exclude |
| URL present, driver missing | url but no driver class | Cannot load driver class | add the driver dependency |
| Properties file off the classpath | nothing | this error | move to src/main/resources |
| Profile-specific file, profile off | no url | this error | activate the profile |
URL in spring.datasource.hikari.jdbc-url | pooled config only | this error | use spring.datasource.url |
| Multi-datasource beans | auto-config backed off | may still fail on first use | define the bean explicitly |
| Fix | When it is right | When it is wrong |
|---|---|---|
| Set spring.datasource.url | the app must use a database | the app has no persistence |
| Add H2 with test scope | tests only | production startup |
| Exclude DataSourceAutoConfiguration | a library app with no DB | anything that uses JPA |
| Provide a DataSource bean | multiple databases | one database with defaults |
spring.autoconfigure.exclude | tuning specific auto-configs | hiding 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:
jar tf build/libs/app.jar | grep -E 'application.*(properties|yml)'
unzip -p build/libs/app.jar BOOT-INF/classes/application.yml | head -20In 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/appPaste 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:
java -jar app.jar --debug 2>&1 | grep -A5 'DataSourceAutoConfiguration'
SPRING_PROFILES_ACTIVE=prod java -jar app.jar@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:
mvn dependency:tree -Dincludes=org.postgresql:postgresql
./gradlew dependencies --configuration runtimeClasspath | grep -i postgresSet 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:
@SpringBootTest(properties = {
"spring.datasource.url=jdbc:h2:mem:testdb",
"spring.jpa.hibernate.ddl-auto=create-drop"
})
class ServiceIT {}@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:
@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-urlin a plain Boot app. That key belongs to a manually built pooledDataSource; Boot readsspring.datasource.url.- Environment variable naming.
SPRING_DATASOURCE_URLmaps tospring.datasource.url, butSPRING_DATASOURCE_JDBCURLdoes not map tojdbc-url; relaxed binding only handles case and separators, not invented names. - A profile file named
application-dev.ymlbut activated asdevelopment. The suffix must match the profile name exactly. - Spring Boot 3 versus 2 property names.
spring.datasource.initialization-modeis gone in 3.x, andspring.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
DataSourceAutoConfigurationwhile using JPA. The repository layer then fails later with a missingEntityManagerFactory, 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 documentationThe Java documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesAndroid Gradle plugin requires Java 17 to run: where the JDK comes from
Gradle picks its JVM from several places. Make gradle.properties, JAVA_HOME, Studio and CI agree, and stop the stale daemon afterwards.
Maven: release version 25 not supported and where the JDK comes from
Six places choose the JDK and only one matters per build. Diagnose the release error, then pin the compiler so it cannot drift again.
Spring Boot 4: NoClassDefFoundError javax/servlet/http/HttpServlet
Spring Boot 4 runs Jakarta only. A library compiled against javax asks for a class that no longer exists, and the stack trace hides which jar.
ClassNotFoundException vs NoClassDefFoundError in Java
One is a missing lookup, the other a failed link or initialiser. The distinction decides whether you inspect a classpath or a stack trace.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.