Docs Menu
Docs Home
/ / /
Java Sync

Upgrade Driver Versions

On this page

  • Overview
  • Breaking Changes
  • Server Release Compatibility 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 Breaking Changes section. To learn more about the MongoDB Server release compatibility changes, see the Server Release Compatibility Changes section.


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 driver ends support for connecting to MongoDB Server versions v3.4 and earlier. To learn more about this change, see the Version 4.8 Server Release Support Changes section.

  • You must add an explicit dependency on the org.bson.codecs.record module if your application deploys the driver in an OSGi container and relies on the driver for encoding and decoding Java records.

  • The RecordCodec, implemented in v4.6, deserialized POJOs and record classes that are specified as type parameters of List or Map fields of a record as Document values instead of their respective classes. This version now deserializes them to the proper record and POJO types.

    For example, the following record class definitions show a Book record that contains a List that receives a Chapter type parameter:

    public record Book(String title, List<Chapter> chapters) {}
    public record Chapter(Integer number, String text) {}

    Starting in this version, the codec deserializes data in the List into Chapter record classes instead of Document values.

  • The setWindowFields builder API is no longer beta. The new builder breaks binary and source compatibility. See the Aggregates API documentation for information the new setWindowFields() method signatures.

    If your application uses this builder in a version prior to v4.7, update your source code to use the new method signature and rebuild your binary.

  • 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.

A server release compatibility change is a modification to the MongoDB Java Driver that discontinues support for a set of MongoDB Server versions.

The driver discontinues support for a MongoDB Server version after it reaches end-of-life (EOL).

To learn more about the MongoDB support for EOL products, see the Legacy Support Policy.

  • The v4.8 driver drops support for MongoDB Server v3.4 and earlier. To use the v4.8 driver, your MongoDB Server must be v3.6 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

← Compatibility