Introduction

Cannot load driver class: org.h2.Driver means Spring Boot tried to configure a JDBC data source, but the H2 driver was not actually available on the runtime classpath. The error looks like a datasource configuration issue, but most of the time the real problem is dependency setup. Fixing it usually means aligning the H2 dependency, the runtime scope, and the datasource properties.

Start with the H2 Dependency

For Maven, the normal dependency is:

1<dependency>
2  <groupId>com.h2database</groupId>
3  <artifactId>h2</artifactId>
4  <scope>runtime</scope>
5</dependency>

For Gradle:

dependencies {
    runtimeOnly 'com.h2database:h2'
}

If the dependency is missing, excluded, or not available at runtime, Spring Boot cannot load org.h2.Driver even if your configuration points to it correctly.

That is why the first question should be "is H2 present in the runtime classpath," not "is my URL typo-free."

Let Spring Boot Autoconfigure the Driver When Possible

In many cases you do not need to set the driver class explicitly at all. Spring Boot can infer it from the JDBC URL if H2 is on the classpath.

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=

If the dependency is correct, this is often enough.

Manually setting:

spring.datasource.driver-class-name=org.h2.Driver

is fine, but it should not be used to compensate for a missing dependency. It only tells Spring which class to load. It does not make the class exist.

Check the Actual Build Output, Not Just the Build File

A dependency can look correct in the build file and still be absent in the real runtime artifact because of packaging or IDE issues.

Useful checks:

mvn dependency:tree

or:

./gradlew dependencies

These help confirm that H2 is resolved and not being excluded or shadowed.

If you are running from an IDE, reload the project after changing dependencies. IDE classpaths can lag behind build-file edits and produce confusing results.

Watch for Profile and Environment Mismatches

Sometimes H2 is only meant for local development, while another profile is supposed to use PostgreSQL, MySQL, or a different datasource. If the wrong Spring profile is active, Boot may try to initialize a datasource with H2 settings even though the H2 dependency is not present in that environment.

That makes the error look random when it is actually profile drift.

Check which configuration files are active and whether a profile-specific datasource definition is overriding what you think the app is using.

H2 Console and Dev-Only Setup Are Separate Concerns

If you want the H2 console too, enable it explicitly.

spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

This is useful for development, but it does not fix the driver-loading error by itself. The console depends on the same underlying requirement: the H2 driver must actually be available at runtime.

Do a Clean Rebuild After Fixing the Classpath

Once the dependency and configuration are corrected, do a clean rebuild.

mvn clean spring-boot:run

or:

./gradlew clean bootRun

This helps eliminate stale output or cached IDE state. Driver-class errors are often simple, but stale runtime artifacts can make them look persistent after the actual fix is already in place.

Common Pitfalls

• Setting spring.datasource.driver-class-name=org.h2.Driver without actually adding the H2 dependency.
• Adding H2 in the wrong scope so it is present for compile time but absent at runtime.
• Assuming the build file change is active in the IDE without reimporting or rebuilding.
• Debugging datasource properties first when the real issue is classpath resolution.
• Forgetting that Spring profiles may be selecting a different datasource configuration than expected.

Summary

• The error means Spring Boot cannot find the H2 JDBC driver class at runtime.
• The first fix is usually adding or correcting the H2 dependency, especially its runtime scope.
• Spring Boot can often infer the driver from the JDBC URL if the dependency is present.
• Check the real resolved dependency graph, not just the build file text.
• Rebuild cleanly after fixing the classpath so stale artifacts do not hide the result.