Docs Menu

Docs HomeDevelop ApplicationsMongoDB DriversJava

Upgrade Driver Versions

On this page

  • Overview
  • Breaking Changes

In this section, you can identify the changes you need to make to your application to upgrade your driver to a new version.

Before you upgrade, perform the following actions:

  • Ensure the new version is compatible with the MongoDB Server versions your application connects to and the Java Runtime Environment (JRE) your application runs on. See the Java Compatibility page for this information.

  • Address any breaking changes between the current version of the driver your application is using and your planned upgrade version in the section on Breaking Changes below.


To minimize the amount of changes your application may require when upgrading driver versions in the future, use the Stable API.

A breaking change is a modification in a convention or behavior in a specific version of the driver that may prevent your application from working properly if not addressed before upgrading.

The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions. For example, if you are upgrading the driver from v4.0 to v4.5, address all breaking changes from the version after v4.0 including any listed under v4.5.

  • The ObjectId class and its serialVersionUID field were updated to use a new format that minimizes serialization compatibility issues across different versions of the driver.

    If an application using this version or later of the driver attempts to perform Java Object Serialization on any objects that contain an ObjectId and were serialized by a prior version of the driver, Java throws an InvalidClassException.

    To learn more about Java Object Serialization, see the Java Documentation on Serializable Objects.

  • Several classes and methods marked as deprecated in the 3.12 release were removed in this version.

  • The insert helper methods return an insert result object instead of void.

  • The toJson() methods on BsonDocument, Document, and DbObject return a relaxed JSON format instead of a strict JSON format. This makes the JSON documents more readable, but can make it more difficult to identify the BSON type information, such as the difference between a 32-bit and 64-bit integer. If your application relies on the strict JSON format, use the strict mode when reading or writing data. Learn how to specify the JSON format in the current API in the Document Data Format: Extended JSON guide.

  • The default BSON representation of java.util.UUID value was changed from JAVA_LEGACY to UNSPECIFIED. Applications that store or retrieve UUID values must explicitly specify which representation to use. You can specify the representation in the uuidRepresentation property of MongoClientSettings.

    The UUID representation that you specify strictly controls how the driver decodes UUIDs. In previous versions of the driver, if you specified the JAVA_LEGACY representation, the driver would decode binary objects of subtypes 3 and 4 as UUIDs. In version 4.0, the JAVA_LEGACY representation works only with subtype 3.

    For a list of members in the UuidRepresentation enum, see the v4.0 API documentation.

  • The connection pool no longer restricts the number of wait queue threads or asynchronous tasks that require a connection to MongoDB. The application should throttle requests as necessary rather than depend on the driver to throw a MongoWaitQueueFullException.

  • The driver no longer logs using the java.util.logging (JUL) package and only supports the SLF4J logging framework.

  • The embedded and Android drivers were removed. If your application relies on these drivers, you must continue to use a 3.x Java driver version.

  • The uber JARs, mongo-java-driver and mongodb-driver, are no longer published. If your application relies on one of these, you must switch to either mongodb-driver-sync or mongodb-driver-legacy depending on which API the application uses. Make sure you remove the uber JARs from your dependencies.

  • Updates to several classes introduced binary compatibility breaks, such as the method signature change to the insert helper methods. Recompile any classes that link to the driver against this version or later to ensure that they continue to work.

←  CompatibilityMigrate from the Legacy API →