Introduction

WordPress displays "Error establishing a database connection" when it cannot reach the MySQL/MariaDB server. When using a custom socket path (common in Docker, managed databases, or custom MySQL installations), the default localhost connection method fails because WordPress tries TCP instead of the Unix socket. The error appears as:

bash
Error establishing a database connection

And the PHP error log shows: `` PHP Warning: mysqli_real_connect(): (HY000/2002): No such file or directory

Symptoms

  • WordPress shows "Error establishing a database connection" on all pages
  • wp-admin is inaccessible with the same error
  • WP-CLI commands fail with database connection errors
  • MySQL is running and accessible via command line with the socket
  • Other applications on the same server can connect to MySQL using the socket

Common Causes

  • DB_HOST set to localhost causes MySQL to use the default socket path, not the custom one
  • MySQL socket file moved to non-standard location (e.g., Docker volume mount)
  • Socket file permissions prevent the web server user (www-data) from accessing it
  • DB_HOST does not use the 127.0.0.1:/path/to/socket syntax that WordPress requires
  • MySQL skip-networking enabled, preventing TCP fallback

Step-by-Step Fix

  1. 1.Find the actual MySQL socket path:
  2. 2.```bash
  3. 3.mysql -u root -p -e "SHOW VARIABLES LIKE 'socket';"
  4. 4.# Or check the MySQL config
  5. 5.grep socket /etc/mysql/mysql.conf.d/mysqld.cnf
  6. 6.`
  7. 7.Common paths: /var/run/mysqld/mysqld.sock, /var/lib/mysql/mysql.sock, /tmp/mysql.sock
  8. 8.Configure wp-config.php with the correct socket path:
  9. 9.```php
  10. 10.// For a Unix socket connection
  11. 11.define('DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock');

// Other database settings remain the same define('DB_NAME', 'wordpress_db'); define('DB_USER', 'wp_user'); define('DB_PASSWORD', 'your_password'); define('DB_CHARSET', 'utf8mb4'); define('DB_COLLATE', ''); ```

  1. 1.Verify socket file permissions:
  2. 2.```bash
  3. 3.ls -la /var/run/mysqld/mysqld.sock
  4. 4.# Should be readable by www-data
  5. 5.sudo chown mysql:www-data /var/run/mysqld/mysqld.sock
  6. 6.sudo chmod 755 /var/run/mysqld/
  7. 7.`
  8. 8.Test the connection from the command line using the same method WordPress uses:
  9. 9.```bash
  10. 10.php -r "mysqli_connect('localhost:/var/run/mysqld/mysqld.sock', 'wp_user', 'your_password', 'wordpress_db') or die(mysqli_connect_error());"
  11. 11.`
  12. 12.If this prints nothing, the connection is successful.
  13. 13.For Docker-based WordPress, use the service name as DB_HOST or the socket volume:
  14. 14.```yaml
  15. 15.# docker-compose.yml
  16. 16.services:
  17. 17.wordpress:
  18. 18.environment:
  19. 19.WORDPRESS_DB_HOST: db
  20. 20.WORDPRESS_DB_USER: wp_user
  21. 21.WORDPRESS_DB_PASSWORD: your_password
  22. 22.WORDPRESS_DB_NAME: wordpress_db
  23. 23.`

Prevention

  • Document the MySQL socket path in your server configuration documentation
  • Include socket path verification in your WordPress migration checklist
  • Use TCP connection (127.0.0.1) instead of socket if socket path issues persist
  • Monitor MySQL socket file existence and permissions with a health check script
  • Add database connectivity tests to your WordPress deployment verification process
  • For managed databases (RDS, Cloud SQL), always use TCP hostname instead of socket paths