PHP error guide

PDO "could not find driver": Install and Enable the Correct PHP Driver

fatal exception Affects: All PHP versions with PDO Last verified:

Error summary

PDO has no driver for the DSN prefix (often `mysql:`). Install/enable the matching PDO driver for the same PHP SAPI that runs the site, then restart PHP-FPM/Apache.

What it means

PDO has no driver for the DSN prefix (often mysql:). Install/enable the matching PDO driver for the same PHP SAPI that runs the site, then restart PHP-FPM/Apache.

What the error means

The PDO extension is present enough to construct PDO, but the driver module for that database (pdo_mysql, pdo_pgsql, …) is not loaded.

Why PHP produces it

PDO is modular. mysql:host=... requires pdo_mysql (and usually the underlying client libraries).

PHP version notes

Exact package names differ by distro and PHP minor version.

Most common causes

  • pdo_mysql not installed for the active PHP version
  • CLI has the driver but FPM does not
  • Wrong DSN prefix
  • Container image missing DB extensions

Minimal examples

BAD — reproduces the problem

php 
$pdo = new PDO('mysql:host=127.0.0.1;dbname=app', $user, $pass);

FIXED — safer pattern

php 
if (!extension_loaded('pdo_mysql')) {\n    throw new RuntimeException('Enable pdo_mysql');\n}\n$pdo = new PDO('mysql:host=127.0.0.1;dbname=app;charset=utf8mb4', $user, $pass, [\n    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,\n]);

Step-by-step diagnosis

  1. Print PDO::getAvailableDrivers() in the failing SAPI.
  2. Compare php -m for CLI vs FPM phpinfo modules.
  3. Confirm DSN starts with an installed driver name.

Fixes

Fix #1: Install pdo_mysql for the site PHP version

Package names vary; install for the same version Virtualmin/FPM uses.

bash 
php -m | grep -i pdo\n# install php-mysql / php8.3-mysql (distro-specific)\nsudo systemctl restart php-fpm

Fix #2: Verify drivers in code

Fail fast with a clear message during bootstrap.

php 
if (!in_array('mysql', PDO::getAvailableDrivers(), true)) {\n    throw new RuntimeException('pdo_mysql is not enabled');\n}

Common mistakes when fixing it

  • Installing mysqli but not pdo_mysql when the app uses PDO

How to prevent it

  • Composer ext-pdo_mysql requirement
  • Smoke test DB bootstrap in deploy

Web server / environment notes

Docker/Alpine images often omit DB drivers by default

Tags: fpm,cli,docker,linux

Categories

Relevant ZendStudio.net tools