Skip to content
javahacks.dev
Hibernate

Fix SQLException No Suitable Driver Found for JDBC URL

Fix No suitable driver found by checking the driver jar is on the runtime classpath, the URL prefix is right and the registration survived packaging.

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

The application tries to open a database connection and fails with a message that sounds like a missing file:

Text
java.sql.SQLException: No suitable driver found for jdbc:postgresql://localhost:5432/shop

java.sql.DriverManager keeps a list of registered JDBC drivers. When you ask it for a connection, it offers the URL to each driver in turn, and the first one that recognizes the URL's prefix handles it. This message means that no registered driver accepted the URL: either there is no driver at all, or there is one that does not match the prefix. The driver jar is almost always the problem, and it is missing, malformed or hidden in one of five ways. This post reproduces the error, shows how to check from code what is registered, and walks through each cause. Examples use Java 25, the PostgreSQL JDBC driver 42.7 and Spring Boot 4; the output below was produced by running the code on JDK 17.

Cause 1: the driver is not on the runtime classpath

Reproduce the error with no driver jar:

src/main/java/dev/javahacks/jdbc/Drv.javajava
import java.sql.*;

public class Drv {

    public static void main(String[] args) throws Exception {
        try {
            DriverManager.getConnection("jdbc:postgresql://localhost:5432/shop", "u", "p");
        } catch (SQLException e) {
            System.out.println(e.getMessage() + " | state=" + e.getSQLState());
        }
        var drivers = DriverManager.getDrivers();
        int n = 0;
        while (drivers.hasMoreElements()) {
            System.out.println(drivers.nextElement().getClass().getName());
            n++;
        }
        System.out.println("registered=" + n);
    }
}
Text
No suitable driver found for jdbc:postgresql://localhost:5432/shop | state=08001
registered=0

registered=0 is the answer: nothing is registered, so no URL can match. The state 08001 is the SQL standard's code for "unable to establish connection". Add the driver jar to the classpath and the same program registers it:

Shell
java -cp .:postgresql-42.7.4.jar Drv
Text
org.postgresql.Driver
registered=1

(and then the connection attempt itself proceeds and fails with a different message, Connection refused, if no server runs, as in PSQLException connection refused). In a Maven project the usual slip is the dependency scope. A test or provided scope keeps the driver out of the packaged application:

pom.xmlXML
<!-- Wrong: present for tests, absent from the jar -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>

<!-- Right: available at runtime -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

The runtime scope puts the jar in the packaged application but not on the compile classpath, which is exactly right for a driver you reach only through JDBC. The scopes are explained in Maven dependency scopes with examples. Confirm what is packaged:

Shell
unzip -l target/shop.jar | grep -i postgresql
Text
 1089245  BOOT-INF/lib/postgresql-42.7.4.jar

No line means the jar never made it into the application. In Gradle the equivalent is runtimeOnly 'org.postgresql:postgresql', and the mistake is testImplementation or no declaration at all. Running from an IDE can hide this: the IDE may put test-scope jars on the run classpath, so the application works there and fails in the packaged jar.

Cause 2: the URL prefix does not match

A driver accepts a URL only if it starts with its own prefix. A near miss is the same failure:

DatabaseCorrect prefixCommon mistakes
PostgreSQLjdbc:postgresql://jdbc:postgres://, postgresql:// (no jdbc:)
MySQLjdbc:mysql://jdbc:mysql:/
MariaDBjdbc:mariadb://jdbc:mysql:// with only the MariaDB driver
SQL Serverjdbc:sqlserver://jdbc:mssql://
H2jdbc:h2:mem: or jdbc:h2:file:jdbc:h2://
Oraclejdbc:oracle:thin:@jdbc:oracle://

Print the exact string the application uses, including what environment variables and profiles produced, and compare character by character. Hosting platforms often hand you a connection string in a different form: a Heroku-style postgres://user:pass@host/db URL is not a JDBC URL and must be converted to jdbc:postgresql://host/db with the credentials supplied separately. A trailing space, a quoted value copied with its quotes, or an unresolved placeholder like ${DB_URL} that was never substituted all produce the same message:

Text
No suitable driver found for ${DB_URL}

When the text after for is not a URL, the configuration, not the driver, is at fault. The driver-specific URL syntax is in the PostgreSQL JDBC documentation.

Cause 3: registration was lost in packaging

Since JDBC 4, drivers register themselves through the service loader: the driver jar contains a file META-INF/services/java.sql.Driver naming its driver class, and DriverManager reads it at startup. Anything that breaks that file breaks registration while the classes are still present. Building a fat jar by merging all dependencies into one with a plugin that does not merge service files keeps only one java.sql.Driver file, and with two databases in the project, one driver vanishes. With the Maven Shade plugin, add the service transformer:

pom.xmlXML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <configuration>
    <transformers>
      <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
    </transformers>
  </configuration>
</plugin>

Spring Boot's own repackaging keeps the jars nested and intact, so this affects Shade, the Gradle shadowJar plugin (use mergeServiceFiles()) and the Maven assembly plugin with a jar-with-dependencies descriptor. Check the merged file:

Shell
unzip -p target/app-shaded.jar META-INF/services/java.sql.Driver
Text
org.postgresql.Driver
com.mysql.cj.jdbc.Driver

If the file lists only one of the two drivers you expect, that is the cause. Minimizing options (minimizeJar) can also strip a class that is only reached through the service file, so exclude drivers from minimization.

An alternative for old code is to register explicitly: Class.forName("org.postgresql.Driver"). That works on any version, but it is a workaround for a packaging problem you should fix; it also fails with ClassNotFoundException if the jar is truly absent, which is the clearer error. Use it to confirm the diagnosis: if Class.forName succeeds and the connection then works, registration was the problem; if it throws, the jar is missing.

Cause 4: application servers and class loaders

In an application server or servlet container, DriverManager belongs to the JDK, which lives in a different class loader from your web application. A driver jar inside WEB-INF/lib is visible to the web application's loader, and DriverManager only returns drivers that the calling code's loader can see. The common setups:

  • Driver in the web application, connection from the application. Works, since caller and driver share a loader.
  • **Driver in the server's lib directory, a datasource defined by the server.** The server registers the driver and your code asks JNDI for a DataSource, so DriverManager is not involved.
  • Driver in both places. Two copies, each registered under a different loader, and a connection pool in one cannot see the driver in the other. Remove the duplicate.
  • A pool library (HikariCP, Tomcat JDBC) in the server and the driver in the application, or the reverse. The pool loads the driver by name through its own loader, which cannot see the application's.

Put the driver where the code that loads it lives. For a server-managed datasource, the jar belongs in the server's shared library directory, and the application declares it provided. The loader details, and the tools to find which jar supplied a class, are in debugging classpath and class loading problems. Tomcat also warns when an application leaks a driver on undeploy, which is a sign the driver is in the wrong place.

Cause 5: an environment variable or profile left the URL empty

Spring Boot reads the URL from spring.datasource.url, and a profile or an environment variable can override it with something empty. A deployment where SPRING_DATASOURCE_URL is set to an empty string overrides the file with nothing, and the application reports a different message first:

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

That is Boot noticing the missing URL, covered in Failed to configure a DataSource. If you build the data source yourself with DriverManagerDataSource or DataSourceBuilder, the empty URL can reach DriverManager and give No suitable driver found for followed by nothing. Check the effective value at startup:

java
@Bean
ApplicationRunner showUrl(@Value("${spring.datasource.url:<unset>}") String url) {
    return args -> System.out.println("jdbc url = [" + url + "]");
}

The brackets make leading and trailing whitespace visible. The profile in use decides which file's value wins; in the cluster, check the Deployment's environment (kubectl set env deployment/shop --list). An environment variable name that is slightly wrong (SPRING_DATASOURCE_URI) is silently ignored, so the file's value, perhaps a test placeholder, is used instead.

Check from code

When you cannot tell which cause applies, ask the process. This snippet prints the registered drivers, whether the driver class can be loaded, and where it came from:

java
public static void diagnose(String url) {
    System.out.println("url = [" + url + "]");
    DriverManager.drivers().forEach(d -> System.out.println("registered: " + d.getClass().getName()));
    try {
        Class<?> c = Class.forName("org.postgresql.Driver");
        System.out.println("loaded from: " + c.getProtectionDomain().getCodeSource().getLocation());
    } catch (ClassNotFoundException e) {
        System.out.println("driver class not on the classpath");
    }
    try {
        System.out.println("accepts url: " + DriverManager.getDriver(url).getClass().getName());
    } catch (SQLException e) {
        System.out.println("no driver accepts the url: " + e.getMessage());
    }
}

Read the four answers in order: the URL as the process sees it, which drivers registered, whether the class exists and where it came from, and whether any registered driver accepts this URL. The first line that surprises you is the cause. Related failures that appear next on a correct setup are pool exhaustion, described in connection is not available, request timed out.

Where this does not apply

If the message is ClassNotFoundException: org.postgresql.Driver you named the driver class explicitly and it is missing, which is cause 1 with a clearer message. If the connection fails with Connection refused, password authentication failed or database does not exist, the driver was found and the problem is further along. And with a managed datasource configured entirely by the container, DriverManager is not involved, so look at the server's datasource definition and its driver module instead. The behavior of the registry is specified in the DriverManager Javadoc.

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.