Fix: Spring Boot Failed to Configure a DataSource

The Error

Spring Boot fails to start with:

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 auto-configured by Spring Boot, perhaps you forgot to
  specify the database connection details?

Or:

APPLICATION FAILED TO START

Description:
Cannot determine embedded database driver class for database type NONE

Action:
If you want an embedded database, please put it on the classpath.

Or after adding database properties, a different error:

org.springframework.boot.autoconfigure.jdbc.DataSourceProperties$DataSourceBeanCreationException:
Failed to determine a suitable driver class

Why This Happens

Spring Boot’s auto-configuration detects spring-data-jpa, spring-jdbc, or any JPA/database dependency on the classpath and automatically tries to configure a DataSource. If no database URL is provided, it looks for an embedded database (H2, HSQL, Derby) on the classpath. If it finds neither, it fails.

• Database dependency added without connection properties — you added spring-boot-starter-data-jpa but didn’t configure spring.datasource.url in application.properties.
• Wrong property file loaded — your database properties are in application-dev.properties but the dev profile isn’t activated, so Spring Boot reads application.properties which has no database config.
• H2 not on classpath for tests — you use a real database in production but want H2 for tests. H2 isn’t added as a test dependency.
• Driver class not found — the database driver JAR isn’t on the classpath (missing Maven/Gradle dependency).
• Placeholder values not replaced — spring.datasource.url=${DB_URL} but the DB_URL environment variable isn’t set, leaving the URL as the literal ${DB_URL} string.

Fix 1: Add Database Connection Properties

Add the required properties to src/main/resources/application.properties:

PostgreSQL:

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=myuser
spring.datasource.password=mypassword
spring.datasource.driver-class-name=org.postgresql.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

MySQL:

spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC
spring.datasource.username=myuser
spring.datasource.password=mypassword
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect

H2 (in-memory, for development/testing):

spring.datasource.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop
spring.h2.console.enabled=true   # Enable H2 browser console at /h2-console

Fix 2: Add the Database Driver Dependency

Without the JDBC driver on the classpath, Spring Boot can’t connect even with correct properties.

Maven — pom.xml:

<!-- PostgreSQL -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- MySQL -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- H2 (for tests or embedded dev) -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>  <!-- or scope: test for test-only -->
</dependency>

Gradle — build.gradle:

dependencies {
    // PostgreSQL
    runtimeOnly 'org.postgresql:postgresql'

    // MySQL
    runtimeOnly 'com.mysql:mysql-connector-j'

    // H2 (test only)
    testRuntimeOnly 'com.h2database:h2'
}

After adding dependencies, reload/reimport your Maven or Gradle project.

Fix 3: Activate the Correct Profile

If database properties are in a profile-specific file (e.g., application-dev.properties), activate the profile:

application.properties (base):

# No database config here — it's profile-specific
spring.application.name=myapp

application-dev.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb_dev
spring.datasource.username=dev_user
spring.datasource.password=dev_pass

application-prod.properties:

spring.datasource.url=${POSTGRES_URL}
spring.datasource.username=${POSTGRES_USER}
spring.datasource.password=${POSTGRES_PASSWORD}

Activate the profile:

# Run with dev profile
java -jar myapp.jar --spring.profiles.active=dev

# Or via environment variable
export SPRING_PROFILES_ACTIVE=dev
java -jar myapp.jar

# In application.properties (always activate dev locally)
spring.profiles.active=dev

In IntelliJ: Run/Debug Configurations → Active profiles → dev

Pro Tip: Use YAML format for cleaner multi-profile configuration in a single file:

# application.yml
spring:
  profiles:
    active: dev
---
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb_dev
    username: dev_user
    password: dev_pass
---
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: ${POSTGRES_URL}
    username: ${POSTGRES_USER}
    password: ${POSTGRES_PASSWORD}

Fix 4: Exclude DataSource Auto-Configuration

If your application doesn’t need a database at all (you added JPA transitively but don’t use it), exclude the auto-configuration:

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class
})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Or via application.properties:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
  org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

This is the right fix if you’re using a non-JPA data store (MongoDB, Redis, Elasticsearch) but accidentally pulled in a JPA dependency.

Fix 5: Fix Environment Variable Placeholders

If properties reference environment variables that aren’t set, Spring Boot uses the literal placeholder string as the value:

spring.datasource.url=${DATABASE_URL}

If DATABASE_URL isn’t set, Spring Boot gets the string ${DATABASE_URL}, which is not a valid JDBC URL.

Set the environment variables before running:

export DATABASE_URL=jdbc:postgresql://localhost:5432/mydb
export DATABASE_USERNAME=myuser
export DATABASE_PASSWORD=mypassword
java -jar myapp.jar

Or provide a default value:

spring.datasource.url=${DATABASE_URL:jdbc:postgresql://localhost:5432/mydb_default}
spring.datasource.username=${DATABASE_USERNAME:dev_user}
spring.datasource.password=${DATABASE_PASSWORD:dev_pass}

The syntax ${VAR:default} uses the environment variable if set, or falls back to the default.

Verify the resolved value:

# Enable actuator and check environment
curl http://localhost:8080/actuator/env | jq '.propertySources[] | select(.name | contains("application")) | .properties'

Fix 6: Configure H2 for Tests Only

Use a real database in production/dev but H2 for unit/integration tests:

src/main/resources/application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=myuser
spring.datasource.password=mypassword

src/test/resources/application.properties:

# Overrides main properties for tests
spring.datasource.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

build.gradle / pom.xml:

<!-- H2 as test dependency only -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>test</scope>
</dependency>

Fix 7: Configure Multiple DataSources

If you have multiple databases, you must explicitly configure each DataSource bean — Spring Boot’s auto-configuration only works for a single DataSource:

@Configuration
public class DataSourceConfig {

    @Bean
    @Primary
    @ConfigurationProperties("spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties("spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }
}

spring.datasource.primary.url=jdbc:postgresql://localhost:5432/primary_db
spring.datasource.primary.username=user1
spring.datasource.primary.password=pass1

spring.datasource.secondary.url=jdbc:postgresql://localhost:5432/secondary_db
spring.datasource.secondary.username=user2
spring.datasource.secondary.password=pass2

When configuring multiple DataSources manually, Spring Boot’s auto-configuration backs off. You must configure JPA entities and repositories explicitly for each DataSource.

Still Not Working?

Enable Spring Boot debug logging to see exactly what auto-configuration ran and why:

java -jar myapp.jar --debug

Look for DataSourceAutoConfiguration in the output — “matched” means it ran, “did not match” shows what condition failed.

Check the full classpath for conflicting drivers:

# Maven
mvn dependency:tree | grep -E "(jdbc|driver|datasource)"

# Gradle
./gradlew dependencies | grep -E "(jdbc|driver|datasource)"

Verify the JDBC URL format. A malformed URL causes a “suitable driver class” error even when the driver is present:

# PostgreSQL
jdbc:postgresql://host:port/database

# MySQL
jdbc:mysql://host:port/database

# H2 in-memory
jdbc:h2:mem:dbname

# H2 file-based
jdbc:h2:file:/path/to/db

For related Spring Boot issues, see Fix: Spring Boot Circular Dependency and Fix: Spring Boot Port Already in Use.