Laravel: PDOException could not find driver

The error

PDOException

could not find driver

Laravel usually wraps it:

Illuminate\Database\QueryException
could not find driver (Connection: mysql, SQL: select ...)

What it means

PDO is installed, but the driver for your specific database is not. PHP has a separate extension per database - pdo_mysql, pdo_pgsql, pdo_sqlite - and the connection you configured needs the one that is missing.

Note what it is not. It is not wrong credentials, which say access denied. It is not an unreachable server, which says connection refused. The database has not been contacted at all; PHP cannot make the attempt.

Confirm which driver is missing

php -m | grep pdo
php -r "var_dump(PDO::getAvailableDrivers());"

Then check what the application is asking for:

php artisan tinker --execute="echo config('database.default');"

If config('database.default') is pgsql and the driver list contains only mysql and sqlite, that is the whole fault.

Install the right extension, for the right PHP

The version in the package name has to match the PHP that runs your application:

php -v                                   # check this first
 
# Debian / Ubuntu
sudo apt install php8.3-mysql            # or php8.3-pgsql
sudo systemctl restart php8.3-fpm
 
# RHEL / Alma / Rocky
sudo dnf install php-mysqlnd             # or php-pgsql
sudo systemctl restart php-fpm

Installing php-mysql without the version prefix on a machine with several PHP versions installs it for the default one, which is often not the one your site runs. That is the most common reason this error survives an apparently successful install.

In Docker

The official images include no database drivers:

FROM php:8.3-fpm
 
RUN docker-php-ext-install pdo_mysql
 
# for Postgres, the client library is needed at build time
RUN apt-get update \
 && apt-get install -y libpq-dev \
 && docker-php-ext-install pdo_pgsql

Rebuild the image rather than restarting the container - the extension is baked in at build time, so a restart changes nothing.

The CLI and web mismatch

Migrations run, the site does not. Two PHP configurations:

php -i | grep "Loaded Configuration File"

<?php phpinfo();   // load this over HTTP and read the same line

Two different paths means two ini files. Enable the extension in the web server's, then restart PHP-FPM - editing the file is not enough on its own.

After it is installed and still missing

php -i | grep extension_dir
ls $(php -r "echo ini_get('extension_dir');") | grep pdo

If the .so file is not in that directory, the package was built for a different PHP version. If it is there and still not loaded, the extension= line is in an ini file that is not being read - check the directory that ini files are scanned from, which php -i | grep "Scan this dir" will name.

One more that costs people an afternoon: with Octane, or any long-running worker, the process holds the PHP it started with. Restarting FPM does not restart those. They need stopping and starting themselves.

Once the driver loads, the next error on a fresh machine is usually about the credentials. Access denied for user looks similar and is not.

The long-running-process case is the general one. A worker holds the code and the runtime it booted with, which is also why Octane exposes a class of bug PHP used to clean up between requests.