Fatal error: Class 'MongoDB\Driver\Manager' not found

Fatal error: Class 'MongoDB\Driver\Manager' not found

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Fatal error: Class 'MongoDB\Driver\Manager' not found

Encountering the Fatal error: Class 'MongoDB\Driver\Manager' not found immediately after instantiating a connection manager suggests one specific issue: the PHP extension is loaded, but the underlying C driver library is missing. This distinction is crucial because modern PHP environments often decouple these two components. When you run phpinfo() and see "mongodb" listed under the Loaded Extensions section, it confirms that the PHP API layer is present. However, this layer relies entirely on a separate compiled library to function. Without that library, the classes defined in the extension cannot be instantiated, resulting in the fatal error you are seeing when attempting to create a MongoDB\Driver\Manager instance.

The root cause of this discrepancy usually stems from how the PHP MongoDB driver is distributed and installed. Historically, the driver was available as a PECL extension (mongodb). While this legacy extension still exists, it requires specific compilation flags or system libraries that are not always included by default in shared hosting environments or standard Docker images. If you attempt to use the MongoDB\Driver namespace (which is part of the newer driver architecture) without ensuring the corresponding C library is linked, PHP will throw this exact fatal error because it cannot resolve the class definition against its system libraries.

To resolve this, you must ensure that the MongoDB C Driver is installed on your system before installing or loading the PHP extension. The installation method depends heavily on your operating system and environment. On Linux systems, for example, you typically need to install the development headers for the driver first. On Ubuntu or Debian, this involves running sudo apt-get install libbson-dev libmongoc-dev. Only after these libraries are present should you proceed to install the PHP extension itself using pecl install mongodb or via a composer package if you are using the newer v2.x+ architecture which bundles the driver differently.

A common pitfall occurs when switching between different versions of the MongoDB PHP driver. The transition from the legacy PECL extension to the new Composer-based driver (often referred to as mongodb/mongodb) changed the internal structure significantly. The old PECL extension exposes classes like MongoDB\Driver\Manager only if it was compiled against a specific version of the C library. If you have updated your system's MongoDB client libraries but haven't recompiled the PHP extension, or vice versa, version mismatch can lead to class resolution failures. Always verify that the php-mongodb extension in your composer.json or PECL installation matches the capabilities of your underlying OS libraries.

In shared hosting environments, such as those provided by many web hosts, you often lack control over system-level packages like libmongoc-dev. In these scenarios, relying on the legacy PECL extension is risky because the host provider may not have pre-linked the necessary C libraries. If you are using a framework like Laravel, ensure that your php.ini file explicitly enables the extension (extension=mongodb.so) and that the server process has access to the correct library paths. If the host cannot install the system libraries, you might need to request support from the provider to pre-configure the environment or consider alternative database solutions if MongoDB integration is non-negotiable.

For developers managing their own servers or containers, the most robust approach is to containerize your application with the C driver libraries baked in. Using an official MongoDB image as a base or layer allows you to install the PHP extension without worrying about missing system dependencies. This ensures that phpinfo() shows the extension as active and that the MongoDB\Driver classes are fully resolvable.

If you continue to face issues where the class is not found despite having the extension loaded, check your php.ini configuration to ensure the extension=mongodb directive is uncommented and that no conflicting versions of the extension are loaded multiple times. Additionally, verify that you are using a PHP version compatible with the driver; very old PHP versions may support only the legacy extension, while newer applications might expect the modern Composer-based driver which handles dependencies differently. By aligning your system libraries, PHP extensions, and application code, you eliminate the fatal error and restore full connectivity to your MongoDB instance.

Our network