MySQLi not found dockerized php

MySQLi not found dockerized php

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

Stefan Bogdanescu

Founder & Senior Architect

MySQLi Not Found in Dockerized PHP: Missing Extensions, Not Drivers

When you encounter a Fatal error: Class 'MySQLi' not found inside a Docker container while Nginx and PHP are otherwise functioning, the issue is almost never about the driver architecture itself. In your specific case, the environment is running PHP 7.1.5 with the mysqlnd extension enabled, as confirmed by your phpinfo output. The core problem is simply that the mysqli extension module has not been compiled or installed within the container's filesystem.

Moving from a native host OS to a Dockerized environment fundamentally changes how extensions are loaded. On a traditional Linux installation, you might have installed MySQLi globally using a package manager like apt or yum, which populates system libraries accessible to PHP. However, Docker containers operate with isolated filesystems. Unless your Dockerfile explicitly installs the specific PHP extension packages required for your application, those binaries simply do not exist inside the container.

To resolve this, you must ensure that the php-mysql or php-mysqli package is included in your build context. For Debian-based images (common with Nginx and PHP stacks), this typically involves running:

RUN apt-get update && apt-get install -y php-mysql \
    && rm -rf /var/lib/apt/lists/*

For Alpine-based images, you would use apk add php7-mysql. The key is to verify that the extension files actually exist after the build completes. You can do this by checking for the presence of .so files in the PHP extensions directory:

ls -l /usr/lib/php/20170713/mysqli.so
# or check your specific version path
find /usr/lib/php -name "mysqli*"

If these files are missing, the php.ini configuration cannot load them, resulting in the class not being recognized at runtime.

Why mysqlnd Isn't Enough

There is often confusion regarding the mysqlnd driver mentioned in your logs. The mysqlnd (MySQL Native Driver) is a specific implementation of the MySQL client library written in C. It provides the low-level communication between PHP and MySQL. However, PHP separates its extension infrastructure into distinct modules. Even if mysqlnd is present and functional (which it appears to be in your screenshots), the higher-level wrapper class mysqli still requires its own compiled extension to be loaded.

In older PHP versions or specific distributions, these might have been bundled differently, but in modern modular setups like PHP 7.x, they are distinct packages. The error indicates that the PHP interpreter knows about the database connection logic generally, but lacks the specific class definition for mysqli.

Configuration and Troubleshooting

Once you have installed the package, you must ensure your php.ini is actually using it. While this usually happens automatically, explicit configuration helps avoid ambiguity:

extension=mysqli

If you are building a custom Docker image based on php:7.1-fpm, ensure that the Dockerfile copies or installs the extension before starting the web server. A common pitfall is installing the extension into a non-standard path and then failing to update php.ini with the correct extension_dir.

Should You Switch Drivers?

You asked if you should use a different driver now. The short answer is no. The mysqli driver remains one of the most robust and standard ways to connect PHP applications to MySQL databases. Unless you have specific performance requirements that mandate switching to PDO or using a different ORM, there is no technical reason to abandon mysqli.

If you are moving toward modern frameworks, consider how your application layer handles database connections. For instance, if you are building with Laravel, the framework abstracts these details away entirely, making the distinction between raw mysqli and PDO less critical for day-to-day development. However, for legacy codebases or custom implementations like yours, ensuring the correct extension is installed in the container is the definitive fix.

Finally, verify your connection string parameters. While the error points to a missing class, ensure that the host, port, and database name passed to new mysqli() match the service discovery mechanism inside your Docker network (e.g., using the container name as the hostname rather than an IP address).

Our network