Upgrading to 3.0

The 3.0 release is incompatible with the 2.x release series. However, where possible, the 2.13.0 driver has deprecated classes or methods that have been removed in 3.0.

Before upgrading to 3.0, compile against 2.13.0 with deprecation warnings enabled and remove use of any deprecated methods or classes.

System Requirements

The minimum JVM is now Java 6: however, specific features require Java 7:

  • SSL support requires Java 7 in order to perform host name verification, which is enabled by default. See below and on SSL for details on how to disable host name verification.
  • The asynchronous API requires Java 7, as by default it relies on AsynchronousSocketChannel for its implementation. See Async for details on configuring the driver to use Netty instead.


The following lists the most significant backwards-breaking changes, along with the recommended solutions.


The driver now enables host name verification by default for SSL connections. If you are knowingly using an invalid certificate, or are using Java 6 (see above), set the sslInvalidHostNameAllowed property to true.


Providing little practical value, the autoConnectRetry and maxAutoConnectRetryTime properties in MongoClientOptions have been removed from the Java driver to be consistent with other MongoDB-supported drivers .


The MongoClient (and ServerAddress) constructors no longer throw UnknownHostException: This breaks source but not binary compatibility, so re-compilation with 3.0 will only succeed after removing any reference to this exception in catch blocks or method throws declarations.


The requestStart and requestDone methods in DB have been removed: These methods have been removed in accordance with the server selection specification.

The authenticate method in DB has been replaced with MongoClient constructors that take MongoCredential instances.


The ensureIndex methods in DBCollection have been removed: replace with the corresponding createIndex method.


The getLastError method in WriteResult has been removed: this method does not work reliably in the 2.x series and there is no way to make work reliably, so it has been removed. Replace with use of an acknowledged WriteConcern when executing the write operation.


The fetch method in DBRef has been removed: use the findOne method instead.