Java cannot load org.postgresql.Driver
java.lang.ClassNotFoundException: org.postgresql.DriverShort 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.
Fix it fast
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 postgresql2Match what you see, then jump to its fix
- 1
mvn dependency:tree prints nothing for postgresqlThe driver dependency is missing from the buildFix - 2
The build is fine, but java -jar or java Main failsYou run java directly and the jar is not on -cpFix - 3
It works in the IDE tests but not when the packaged app runsThe driver is marked provided or test and is missing at run timeFix
- 1
What does the error look like?
java.lang.ClassNotFoundException: org.postgresql.DriverClass 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.xml2Fix
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 postgresqlConfirmed by maven.apache.org
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.Main3Verify
The program connects without the ClassNotFoundException.
java -cp myapp.jar:postgresql-42.7.14.jar com.example.MainConfirmed by jdbc.postgresql.org
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 scope2Fix
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.jarConfirmed by maven.apache.org
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
Databases
Spring Boot cannot configure a DataSource for PostgreSQL
Failed to determine a suitable driver class
Spring Boot builds a pooled DataSource only when it has a JDBC URL and a loadable driver.
3 causes, each with a fixDatabases
H2 in PostgreSQL mode still behaves differently from PostgreSQL
Names or null ordering differ from PostgreSQL in test results
H2 compatibility modes are switched on in the JDBC URL and cover only a small part of the differences between databases.
4 causes, each with a fixDatabases
TypedQuery rejects a query that selects several columns
The select list of the query must contain only a single item
The Jakarta Persistence rule is that the select list of a typed query holds a single item.
4 causes, each with a fixDatabases
PostgreSQL JDBC: an I/O error occurred while sending to the backend
org.postgresql.util.PSQLException: An I/O error occurred while sending to the backend.
This error means the connection the driver was about to use was already closed.
3 causes, each with a fixDatabases
executeQuery on an INSERT or UPDATE throws in PostgreSQL JDBC
No results returned by the query
executeQuery is for statements that return rows.
2 causes, each with a fixDatabases
Saving a UUID through JDBC fails with a type mismatch
Hint: You will need to rewrite or cast the expression.
pgJDBC sends setString parameters as varchar, and PostgreSQL will not store varchar in a uuid column without a conversion.
3 causes, each with a fix