Solving the “PHP Fatal Error: Uncaught PDOException: could not find driver” Problem

Solving the “PHP Fatal Error: Uncaught PDOException: could not find driver” Problem
Photo by Simon Stratford / Unsplash

When building modern PHP applications—especially those using frameworks like Laravel, Symfony, or any project that connects to a database using PDO (PHP Data Objects)—you might encounter a frustrating error like this:

PHP Fatal error:  Uncaught PDOException: could not find driver

This error often happens during local development, Docker builds, or fresh deployments. But what exactly does it mean, and how do you fix it?


Understanding the Error

The message could not find driver is not referring to a missing database like MySQL or PostgreSQL—but to a missing PDO database driver that PHP uses to communicate with your database.

For example:

  • If you're using MySQL, PHP needs the pdo_mysql extension.
  • If you're using PostgreSQL, PHP needs the pdo_pgsql extension.

If these extensions are missing or not loaded, PHP can’t create a PDO connection, and your application crashes.


Common Scenarios Where This Happens

  • You installed PHP but didn’t install the matching PDO driver.
  • You're running PHP in a Docker container but forgot to include the necessary extension in your Dockerfile.
  • You switched to a different version of PHP (e.g. PHP 8.x) but forgot to reinstall or re-enable the extensions.
  • The extension is present, but not enabled in your php.ini.

How to Fix It

1. Install the Required PHP Extension

Choose the one that matches your database:

For MySQL / MariaDB:

# Ubuntu/Debian
sudo apt install php-mysql

# Alpine (commonly used in Docker)
apk add php-pdo_mysql

For PostgreSQL:

# Ubuntu/Debian
sudo apt install php-pgsql

# Alpine
apk add php-pdo_pgsql

2. Restart Your Web Server

After installation, make sure to restart your PHP service:

sudo systemctl restart apache2
# or if you're using Nginx:
sudo systemctl restart php8.2-fpm

3. Check if the Extension is Enabled

Run:

php -m | grep pdo

Expected output:

PDO
pdo_mysql

If nothing shows up, make sure the extensions are enabled in your php.ini. Look for these lines and ensure they are not commented out (remove the ;):

extension=pdo_mysql

Then restart the server again.


How to Avoid This in the Future

  • Use phpinfo() or php -i to inspect your running PHP configuration.
  • If you’re using Docker, always explicitly install extensions in your Dockerfile.
  • In Laravel apps, this often happens during CI/CD. Your CI job should install dependencies, PHP extensions, and run php artisan config:cache properly.
  • Consider using tools like Laravel Sail or Laragon (Windows) that come pre-configured.

Bonus Tip: How to Check Which DB Driver Laravel is Using

If you're unsure which driver Laravel is trying to use, open your .env file:

DB_CONNECTION=mysql

Then, in config/database.php, Laravel maps this to a PDO driver:

'mysql' => [
    'driver' => 'mysql',
    ...
]

So in this case, Laravel will need pdo_mysql.


Finally

This error—"could not find driver"—has nothing to do with your actual database credentials. It’s purely a PHP-level problem caused by missing extensions. The good news? It’s very easy to fix once you know what’s missing.

Make sure the PDO extension for your specific database is installed and loaded, and the error will disappear.

Still stuck? Try running php -i | grep "Loaded Configuration File" to see which php.ini file is being used, and check if the extensions are enabled there.

Support Us