PHP throws "could not find driver" when it opens a PDO connection
PDOException: could not find driverShort answer
PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded. The error means the PHP process that ran the code has no such driver. Check PDO::getAvailableDrivers() in that same runtime, because the command line and PHP-FPM often load different ini files.
Fix it fast
1Find out which cause you have
Ask the runtime that failed which drivers it has. The command line and the web server are separate PHP processes with their own ini files, so a command that works in your terminal proves nothing about the web. Put the check in a script served through the web server, and run the same script on the command line to compare.
<?php // drivers.php: request it through the web server, then run: php drivers.php header('Content-Type: text/plain'); echo php_sapi_name(), "\n"; echo 'php.ini: ', var_export(php_ini_loaded_file(), true), "\n"; echo 'scanned: ', php_ini_scanned_files() ?: '(none)', "\n"; echo 'drivers: ', implode(', ', PDO::getAvailableDrivers()), "\n";2Match what you see, then jump to its fix
- 1
getAvailableDrivers() prints nothing or only sqlite, in both the CLI and the web run, and php -m has no pdo_mysql or pdo_pgsql.The driver extension is not installedFix - 2
php -m shows pdo_mysql, but the web request fails. The drivers.php output differs between the two runs: a different php.ini path, or a different list of scanned files.The CLI has the driver but PHP-FPM or Apache loads a different ini fileFix - 3
PHP prints a startup warning such as "Unable to load dynamic library" in the error log or with php -i, while the driver is still missing from the list.The extension line is there but the driver does not loadFix - 4
Another driver works, but the one in the DSN is absent from the list, for example a pgsql: DSN while only mysql is listed.The DSN names a driver you did not installFix
- 1
What does the error look like?
PDOException: could not find driverFatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12Illuminate\Database\QueryException: could not find driver (Connection: mysql, SQL: ...)
Cause 1 of 4
The driver extension is not installed
1Check
PDO and its sqlite driver come with PHP, but the PHP manual says you may need to enable the driver for your own database. List what the CLI has, then look for the driver in your package manager or build.
php -m | grep -i pdo
# Debian/Ubuntu: find the packages that match your PHP version
apt-cache search --names-only 'php.*(mysql|pgsql)'2Fix
Install the driver for the PHP version you run, then restart whatever runs PHP. In the official php Docker image the extensions are built with the image's own helper; pdo_pgsql also needs the PostgreSQL client library (libpq) available when it is built.
# package manager: pick the names apt-cache printed for your PHP version, for example
sudo apt install php8.3-mysql # pdo_mysql
sudo apt install php8.3-pgsql # pdo_pgsql
sudo systemctl restart php8.3-fpm
# official php Docker image (Dockerfile)
RUN docker-php-ext-install pdo_mysql3Verify
The driver now appears in the list, in the runtime that failed.
php -r 'print_r(PDO::getAvailableDrivers());'Confirmed by php.net
Cause 2 of 4
The CLI has the driver but PHP-FPM or Apache loads a different ini file
1Check
PHP picks php.ini by SAPI (the way PHP is run), so the CLI, FPM and Apache each have their own configuration, and each can scan a different extra directory. Compare the two outputs from the first step, then open the file the failing one reported.
php --ini
# the web side: request drivers.php and read php.ini / scanned
curl -s http://localhost/drivers.php2Fix
Enable the driver in the ini that the failing SAPI loads. Debian-style packages normally do this with one line per extension in that SAPI's conf.d directory. Whatever the layout, list pdo before the driver, and restart the web-side process afterwards because the ini is only read at startup.
; the file the web SAPI reported (path varies by distribution)
extension=pdo
extension=pdo_mysql
extension=pdo_pgsql
sudo systemctl restart php8.3-fpm # or: sudo systemctl restart apache23Verify
Request the script again: the drivers line now lists the driver and both runs agree.
curl -s http://localhost/drivers.php | grep driversConfirmed by php.net
Cause 3 of 4
The extension line is there but the driver does not load
1Check
A line in php.ini is not enough: the extension file must exist inside extension_dir, a Windows build needs the file to be there too, and the PHP manual says PDO must be initialized before database-specific extensions, so the pdo line has to come first. Read PHP's own startup errors, and the directory it searches.
php -i 2>&1 | grep -iE 'warning|extension_dir'
ls "$(php -r 'echo ini_get("extension_dir");')" | grep -i pdo2Fix
Correct the extension_dir or install the missing module, order the lines with pdo first, then restart. On Windows, uncomment the extension lines in php.ini and make sure the matching file exists in extension_dir.
extension_dir = "/usr/lib/php/20230831" ; the directory that holds pdo_mysql.so on your system
extension=pdo
extension=pdo_mysql3Verify
Start-up warnings are gone and the driver is listed.
php -i 2>&1 | grep -ci 'unable to load' # expect 0
php -r 'print_r(PDO::getAvailableDrivers());'Confirmed by php.net
Cause 4 of 4
The DSN names a driver you did not install
1Check
The text before the first colon in the DSN selects the driver: the PHP manual gives mysql: for MySQL and MariaDB and pgsql: for PostgreSQL. Compare it with the list from getAvailableDrivers(), which uses the same names.
grep -rnE "new PDO\(|DB_CONNECTION|DATABASE_URL" . --include=*.php --include=.env 2>/dev/null | head
php -r 'echo implode(",", PDO::getAvailableDrivers());'2Fix
Either install the driver that matches the database you really use, or correct the DSN prefix and parameters to the form the driver documents.
// MySQL or MariaDB
new PDO('mysql:host=127.0.0.1;port=3306;dbname=app;charset=utf8mb4', $user, $pass);
// PostgreSQL
new PDO('pgsql:host=127.0.0.1;port=5432;dbname=app', $user, $pass);3Verify
The constructor now returns without exception.
php -r '$p = new PDO("mysql:host=127.0.0.1;dbname=app", "app", getenv("DB_PASSWORD")); echo $p->getAttribute(PDO::ATTR_DRIVER_NAME), "\n";'Confirmed by php.net
How do I stop it coming back?
- Keep a small diagnostics script (like drivers.php) for deployment checks, and run it through the web server, not only the terminal.
- Install PHP and its extensions from one place per server, and write the extension list in the image or provisioning script rather than by hand.
- Pin the PHP minor version in packages and restart FPM after every upgrade, since ini files and module directories are per version.
- Fail the deploy when PDO::getAvailableDrivers() lacks the driver the app needs.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Databases
The client cannot reach the MySQL or MariaDB server through its Unix socket file
ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2) (MariaDB client wording)
Error 2002 means the client tried the Unix socket file named in the message and found nothing it could talk to.
4 causes, each with a fixDatabases
The MySQL container stops with: the designated data directory is unusable
[ERROR] --initialize specified but the data directory exists. Aborting.
This message closes a failed first start.
3 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
A container cannot resolve the name of its database container
php_network_getaddresses: getaddrinfo failed
127.0.0.11 is Docker's own DNS server for custom networks.
3 causes, each with a fix