The SQLSTATE[HY000] [2002] No such file or directory error in Laravel typically signals that your app can’t locate the MySQL socket file. It’s almost always a server-level misconfiguration not a Laravel code bug.

This issue shows up often in local or shared hosting environments. Fixing it involves updating the correct socket path and syncing your Laravel settings to match.

Why This PDOException Occurs in Laravel

If Laravel can’t talk to MySQL, chances are the socket path is off. It’s not your code  it’s the server setup acting up.

Common Causes:

  • MySQL service isn’t running or installed properly
  • Wrong unix_socket path in config/database.php
  • Missing or broken MySQL socket file (/tmp/mysql.sock)
  • Incorrect .env DB settings (host, port, user and password)
  • Permissions issue with the MySQL socket file

Fixing SQLSTATE[HY000] 2002 Error in Laravel

Laravel fails to connect to MySQL when the socket file is missing or misconfigured. Check the correct socket path and update your config to restore connectivity.

Step 1:  Check Where MySQL’s Hiding the Socket

Pop this into your terminal  it’ll tell you where MySQL is keeping its socket file.

mysql -u root -p -e “SHOW VARIABLES LIKE ‘%sock%’;”

Look for the value under socket. It typically returns something like:

/tmp/mysql.sock

You’ll need to use this exact path in your Laravel config and .env file.

Step 2: Update Laravel’s Configuration Files

Now that you have the correct socket path update your Laravel files:

Update the `.env` file:

DB_SOCKET=/tmp/mysql.sock

config/database.php

Inside the mysql connection section add or update this line:

‘unix_socket’ => env(‘DB_SOCKET’, ‘/tmp/mysql.sock’),

Make sure this section also includes the proper host typically:

‘host’ => env(‘DB_HOST’, ‘127.0.0.1’),

Pro Tip: On some systems using localhost instead of 127.0.0.1 causes Laravel to try socket instead of TCP.

Also Read: The Laravel Helper Functions

Step 3: Restart Services & Clear Laravel Cache

After updating your config, restart MySQL and clear Laravel’s cache:

sudo service mysql restartphp artisan config:clear

php artisan cache:clear

php artisan config:cache

If you’re using brew on Mac:

brew services restart mysql

Step 4: For Docker, Valet or Custom Environments

Docker Users:

If you’re in Docker, skip the socket setup and use the container IP or service name:

DB_HOST=mysqlDB_PORT=3306

Laravel Valet:

For Valet users your socket might be somewhere like:

DB_SOCKET=/Users/yourname/.config/valet/mysql.sock

Find it using:

mysql –print-defaults | grep socket

Final Step: Test the Database Connection

After all the updates, run this to check the connection:

php artisan migrate

If you don’t see the SQLSTATE[HY000] error your configuration is now correct.

Did You Know?

In 2024, over 81% of developers upgraded to Laravel 11 clearly embracing the newest features and improvements. Still, a good number are sticking with Laravel 9 or 10, often to maintain stability or avoid

Common Mistakes to Avoid

Misconfigured socket paths, wrong DB_HOST or skipping cache clearing are the top reasons this error persists. Avoid these to prevent repeated connection failures.

  • Using localhost instead of 127.0.0.1 in .env on Mac
  • Forgetting to restart MySQL after editing configs
  • Typing the wrong socket path (even a missing slash breaks it)
  • Editing config/database.php but not syncing .env

Conclusion

Once you’ve nailed down where that socket file lives, update both .env and config/database.php to match. That’s the real fix.

Restart your services, clear out Laravel’s config cache and hit php artisan migrate. If no errors? You’re golden.