BugWP logo BugWP
Back to Community
Home / Community / Core → Installing wordpress

Troubleshooting WordPress Database Connection and Installation Errors

55 threads Sep 7, 2025 Core → Installing wordpress

Content

Encountering errors during a WordPress installation can be a frustrating experience, especially when they involve the database. A successful installation hinges on a correct and stable connection between WordPress and your MySQL or MariaDB database. Based on community reports, this guide covers the most common database-related installation errors and how to resolve them.

Common Symptoms

Users often report one of the following issues when trying to install WordPress:

  • A blank white screen during the installation process (often on step 2).
  • The critical error: "Error establishing a database connection."
  • Error messages stating that core tables like wp_options "don't exist" even after entering database credentials.
  • The installation script fails to create any tables in the designated database.
  • A database repair attempt fails because it cannot find the tables.

Why This Happens

These errors are almost always related to the connection between the WordPress files (PHP) and the database server (MySQL/MariaDB). The root cause is typically one of the following:

  1. Incorrect Database Credentials: The database name, username, password, or host defined in the wp-config.php file are inaccurate.
  2. Database User Privileges: The database user exists but has not been granted all necessary privileges (e.g., SELECT, INSERT, UPDATE, DELETE, CREATE, DROP) for the specific WordPress database.
  3. Remote Database Connection Issues: When the database is on a separate host (like Amazon RDS, Google Cloud SQL, or a different server on your network), firewalls, security groups, or network policies may be blocking the connection.
  4. Outdated PHP MySQL Extensions: Modern WordPress requires the mysqli extension. If a PHP installation is misconfigured and using the old mysql_connect() function, it will fail.
  5. Socket Authentication (MySQL 8+): Some MySQL 8 installations default to using the auth_socket plugin for user authentication, which is incompatible with WordPress. WordPress requires password-based authentication.
  6. Corrupted File Permissions: The web server user (e.g., www-data on Linux) does not have adequate read/write permissions on the WordPress directory or cannot execute PHP scripts properly.

How to Troubleshoot and Fix It

1. Verify Database Credentials and Connection

First, double-check the fundamentals. The values in your wp-config.php file must be perfect.

  • Database Name: Ensure the database was created exactly as typed.
  • Username & Password: Confirm the user was created and the password is correct. Avoid special characters that might need escaping.
  • Database Host: For local installations, this is almost always localhost. For remote databases, use the exact IP address or hostname provided by your hosting service.

Pro Tip: Test the connection from your web server using the command line. This isolates the problem from WordPress itself.

mysql -u YOUR_DATABASE_USERNAME -p -h YOUR_DATABASE_HOST

After entering the password, try to use the database:

USE YOUR_DATABASE_NAME;

If this command fails, the issue is with your database setup, not WordPress.

2. Check and Grant User Privileges

Creating a user and a database is not enough. The user must have full permissions for that database. Connect to MySQL as a root user and run the following commands, replacing database_user and database_name with your details:

GRANT ALL PRIVILEGES ON database_name.* TO 'database_user'@'localhost';
FLUSH PRIVILEGES;

If your database is on a separate host, use 'database_user'@'%' or a specific IP address instead of @'localhost'.

3. Configure Remote Database Security

If your database is remote (e.g., on Amazon RDS, Google Cloud SQL, or a different VPS), you must explicitly allow connections from your web server's IP address.

  • AWS RDS: Modify the associated security group to allow inbound traffic on port 3306 from your EC2 instance's IP or security group.
  • Google Cloud SQL: Add your Compute Engine VM's IP address to the authorized networks list for the database instance.
  • General Firewalls: Ensure any firewalls (e.g., iptables, ufw) on the database server are configured to allow traffic on port 3306 from the web server's IP.

4. Enable Debugging to See the Real Error

A generic "critical error" or blank screen hides the true problem. Enable debugging in WordPress to see the specific error message.

Open your wp-config.php file (or create one from wp-config-sample.php) and add the following lines:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

This will create a debug.log file in the /wp-content/ directory containing detailed error messages. This log is invaluable for diagnosis. A common error found here is mysqli_real_connect(): (HY000/2002): Permission denied, which often points to a network or firewall issue.

5. Ensure mysqli PHP Extension is Active

WordPress requires the PHP mysqli extension. An error mentioning mysql_connect() is a clear sign this extension is missing. Check your PHP configuration.

  • Run php -m from the command line to list loaded modules and look for mysqli.
  • On Ubuntu/Debian, install it with: sudo apt-get install php-mysql
  • On Windows, ensure extension=mysqli is uncommented in your php.ini file.

6. Switch from Socket to Password Authentication (MySQL 8)

If your MySQL 8 server uses auth_socket for user authentication, WordPress will be unable to connect. You must alter the user to use a password.

Log into MySQL as root and run:

ALTER USER 'your_wordpress_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_strong_password_here';
FLUSH PRIVILEGES;

Conclusion

Most WordPress installation failures related to databases are solvable by methodically checking the connection, credentials, and user permissions. The process involves working both in the database environment and the WordPress file system. By enabling debugging and verifying each step of the connection process, you can identify and resolve the underlying cause, leading to a successful installation.

Related Support Threads Support