Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Java cannot load org.postgresql.Driver

Errorjava.lang.ClassNotFoundException: org.postgresql.Driver

Short answer

The PostgreSQL JDBC jar is not on the classpath of the process that runs your code. Add the org.postgresql:postgresql dependency with the compile or runtime scope, or pass the jar with -cp when you run java by hand. You do not need Class.forName on any current Java.

  • Applies to PostgreSQL JDBC driver 42.7, Maven 3.9, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look for the driver jar in the classpath of the running process. If it is not there, no code change will help.

    ./mvnw dependency:tree | grep postgresql
    # a built jar: unzip -l target/app.jar | grep -i postgresql
  2. 2Match what you see, then jump to its fix

    1. 1mvn dependency:tree prints nothing for postgresqlThe driver dependency is missing from the buildFix
    2. 2The build is fine, but java -jar or java Main failsYou run java directly and the jar is not on -cpFix
    3. 3It works in the IDE tests but not when the packaged app runsThe driver is marked provided or test and is missing at run timeFix

What does the error look like?

  • java.lang.ClassNotFoundException: org.postgresql.Driver
  • Class not found loading JDBC org.postgresql.Driver

Cause 1 of 3

The driver dependency is missing from the build

1Check

The driver is published on Maven Central as org.postgresql:postgresql. Without that dependency, the class is simply not there.

grep -n -A3 "postgresql" pom.xml

2Fix

Add the dependency. Maven's compile scope puts it on every classpath; runtime scope puts it on the runtime and test classpaths.

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.14</version>
  <scope>runtime</scope>
</dependency>

3Verify

The tree now lists the driver.

./mvnw dependency:tree | grep postgresql

Confirmed by maven.apache.org

Did this fix it?

Cause 2 of 3

You run java directly and the jar is not on -cp

1Check

The driver docs say the jar must be included in the class path, either with the CLASSPATH environment variable or flags on the java command line. A plain app jar built without the dependencies does not contain it.

echo "$CLASSPATH"

2Fix

Add the driver jar next to your application on the class path.

java -cp myapp.jar:postgresql-42.7.14.jar com.example.Main

3Verify

The program connects without the ClassNotFoundException.

java -cp myapp.jar:postgresql-42.7.14.jar com.example.Main

Confirmed by jdbc.postgresql.org

Did this fix it?

Cause 3 of 3

The driver is marked provided or test and is missing at run time

1Check

A dependency with the provided scope is left off the runtime classpath, because the container is expected to supply it. With the test scope it exists only for tests.

grep -n -B2 -A4 "<artifactId>postgresql" pom.xml | grep scope

2Fix

Change the scope to runtime (or compile). Keep provided only when the server you deploy to really supplies the driver.

<scope>runtime</scope>

3Verify

Rebuild and run the packaged application.

./mvnw -DskipTests package
java -jar target/app.jar

Confirmed by maven.apache.org

Did this fix it?

How do I stop it coming back?

  • Declare the driver once in the build file and let the build tool resolve it; do not copy jars by hand.
  • Run the packaged jar in CI, not only the IDE, so a missing runtime dependency shows up before release.
  • Do not add Class.forName: the driver docs say it has not been needed since Java 6.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.