Tomcat Warning “To Prevent a Memory Leak, the JDBC Driver Has Been Forcibly Unregistered”

1. Overview

In this tutorial, we’ll look at the Tomcat warning message that informs us that it forcibly unregistered a JDBC driver. We’ll explore the meaning of the message, its root cause, and what we can do to mitigate it.

2. Message and Meaning

A version of the message could be the following:

SEVERE: A web application registered the JBDC driver [oracle.jdbc.driver.OracleDriver]
  but failed to unregister it when the web application was stopped.
  To prevent a memory leak, the JDBC Driver has been forcibly unregistered.

With the above, Tomcat informs us that the JDBC driver class OracleDriver was registered when we deployed the web application, but it wasn’t unregistered when the same application was undeployed.

There are multiple ways we can load and register a JDBC driver, which is essentially a class that extends the java.sql.Driver interface. Tomcat uses the Java Service Provider Interface (SPI) and automatically loads any JDBC 4.0 compatible driver class that it can find under the web application’s WEB-INF/lib directory.

When we undeploy a web application, we must also unregister any drivers it brings. Otherwise, they remain registered with Tomcat. This creates a memory leak until we shut down the whole web server.

Since version 6.0.24, Tomcat detects this type of leak and forcibly unregisters all leaking drivers. However, it still informs us of the issue, which is very helpful if we deploy the same application on another web server that does not support this functionality.

3. Root Cause and Potential Issues

The cause of the issue lies in the improper implementation of the JDBC driver. It should listen to the application undeployment event and unregister itself.

When the Java SPI loads a JDBC driver, it loads it using the current context class loader. Since the driver is under the application’s WEB-INF/lib, SPI loads it using its classloader. Drivers loaded in this way are registered with the DriverManager class, which is a JVM singleton. If this doesn’t happen, it introduces a memory leak in the loaded classes.

When we undeploy the web application, its class loader is garbage collected. On the other hand, the DriverManager still references the JDBC driver preventing garbage collection. If we deploy the same web application again, a new class loader is created, and SPI loads the same JDBC driver a second time. This is effectively a memory leak.

4. Mitigation Measures

There are multiple ways we can mitigate this problem.

4.1. Using Newer Tomcat Version

Since version 6.0.24, Tomcat handles this issue automatically for us. This means that we can safely ignore the warning message.

4.2. Manual Deregistration on Shutdown

We can manually unregister the driver on any application shutdown callback. In the standard case where our application will have one JDBC driver loaded, we can do this with a single line of code:

DriverManager.deregisterDriver(DriverManager.getDrivers().nextElement());

It is important to note that although Tomcat calls the action unregistration, the DriverManager method is called deregistration.

4.3. Moving the JDBC Jar

The official way to handle this is to move the JDBC driver jar file from the application’s WEB-INF/lib to Tomcat’s /lib directory. Since all jars under the /lib directory are also on the classpath, Tomcat will still automatically load the driver but under its own classloader.

Tomcat will not load any driver implementations when we deploy an application since there won’t be any under WEB-INF/lib. This means we can safely undeploy and redeploy it without loading anything new, thus preventing any leaks.

5. Conclusion

In this article, we went over the meaning of the JDBC driver forcible unregistration warning message from Tomcat. We also looked at the root cause of it as well as possible ways to fix it.