Introduction

Spring Boot configures the datasource from application.properties or application.yml. If the JDBC URL contains syntax errors, incorrect hostnames, unencoded special characters in passwords, or wrong port numbers, the application fails at startup with a CannotCreateTransactionException or SQLException. The error is often cryptic because it comes from the underlying JDBC driver, not Spring itself.

Symptoms

  • org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'dataSource'
  • java.sql.SQLException: The connection property 'useSSL' acceptable values are: 'TRUE', 'FALSE', 'YES', 'NO' or '0', '1'
  • java.sql.SQLException: No suitable driver found for jdbc:postgresql//localhost:5432/mydb
  • Communications link failure with Connection refused
  • Application works locally but fails in production/Docker

``` ******* 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, put a supported one on the classpath. If you have database settings, check the URL format. ```

Common Causes

  • Typo in JDBC URL scheme (e.g., jdbc:postgresql// missing colon)
  • Special characters in password not URL-encoded
  • Wrong port number or hostname
  • Missing JDBC driver dependency in pom.xml/gradle
  • SSL parameter format incorrect for the specific driver

Step-by-Step Fix

  1. 1.Verify JDBC URL format for each database:
  2. 2.```properties
  3. 3.# PostgreSQL - CORRECT
  4. 4.spring.datasource.url=jdbc:postgresql://localhost:5432/mydb?sslmode=require

# MySQL - CORRECT spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=true&serverTimezone=UTC

# SQL Server - CORRECT spring.datasource.url=jdbc:sqlserver://localhost:1433;databaseName=mydb;encrypt=true

# WRONG examples: # jdbc:postgresql//localhost:5432/mydb (missing colon after postgresql) # jdbc:mysql://localhost/mydb (missing port) # jdbc:postgresql://localhost:5432/mydb?ssl=true (PostgreSQL uses sslmode, not ssl) ```

  1. 1.URL-encode special characters in credentials:
  2. 2.```properties
  3. 3.# WRONG - password with special characters
  4. 4.spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
  5. 5.spring.datasource.username=admin
  6. 6.spring.datasource.password=p@ssw0rd!# # ! and # cause parsing issues

# CORRECT - URL-encode in connection URL spring.datasource.url=jdbc:postgresql://localhost:5432/mydb?user=admin&password=p%40ssw0rd%21%23

# Or better - use environment variables spring.datasource.url=${DATABASE_URL} spring.datasource.username=${DATABASE_USERNAME} spring.datasource.password=${DATABASE_PASSWORD} ```

  1. 1.Test the connection outside Spring:
  2. 2.```bash
  3. 3.# Using command-line tools
  4. 4.psql -h localhost -p 5432 -U admin -d mydb
  5. 5.mysql -h localhost -P 3306 -u admin -p mydb

# Using a quick Java test public class TestConnection { public static void main(String[] args) throws Exception { String url = "jdbc:postgresql://localhost:5432/mydb"; try (Connection conn = DriverManager.getConnection(url, "admin", "password")) { System.out.println("Connected: " + conn.getMetaData().getURL()); } } } ```

  1. 1.Verify driver is on classpath:
  2. 2.```xml
  3. 3.<!-- pom.xml -->
  4. 4.<!-- PostgreSQL -->
  5. 5.<dependency>
  6. 6.<groupId>org.postgresql</groupId>
  7. 7.<artifactId>postgresql</artifactId>
  8. 8.<scope>runtime</scope>
  9. 9.</dependency>

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

  1. 1.Configure connection pool properly:
  2. 2.```properties
  3. 3.# HikariCP settings (Spring Boot default pool)
  4. 4.spring.datasource.hikari.maximum-pool-size=20
  5. 5.spring.datasource.hikari.minimum-idle=5
  6. 6.spring.datasource.hikari.connection-timeout=30000
  7. 7.spring.datasource.hikari.idle-timeout=600000
  8. 8.spring.datasource.hikari.max-lifetime=1800000

# JDBC URL with pool-relevant parameters spring.datasource.url=jdbc:postgresql://localhost:5432/mydb?\ sslmode=require&connectTimeout=10&socketTimeout=30 ```

Prevention

  • Store database URLs in environment variables, not in code
  • Use @ConfigurationProperties with validation for datasource config
  • Add a health check endpoint that tests actual database connectivity
  • Test JDBC URL format in CI with a testcontainers-based integration test
  • Use Spring Boot's spring.datasource.url validation at startup:
  • ```java
  • @Component
  • public class DataSourceValidator {
  • @PostConstruct
  • public void validate() {
  • String url = dataSource.getUrl();
  • if (!url.startsWith("jdbc:")) {
  • throw new IllegalStateException("Invalid JDBC URL: " + url);
  • }
  • }
  • }
  • `