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.
![PDOException SQLSTATE[HY000] [2002] No Such File or Directory](https://www.esparkinfo.com/wp-content/uploads/2025/07/PDOException-SQLSTATEHY000-2002-No-Such-File-or-Directory-987x658.png)
