Troubleshooting 'Error Establishing a Database Connection'

The 'Error Establishing a Database Connection' message means your application cannot connect to its MySQL database. Working through the causes in order is far quicker than guessing, so follow the steps below from the top.

Check your application's config file

Every database-driven application stores four connection details in a config file. For WordPress that file is wp-config.php in the root of your installation; other applications use different names and locations.

Open the file and check these four values:

• Database host - on shared hosting this should almost always be localhost.
• Database name - the full name including the cPanel account prefix (see the note below).
• Database username - again, the full prefixed name.
• Database password - the password set for that user in cPanel.

For WordPress, the relevant lines in wp-config.php look like this:

define( 'DB_NAME',     'example_mydb' );
define( 'DB_USER',     'example_myuser' );
define( 'DB_PASSWORD', 'yourpassword' );
define( 'DB_HOST',     'localhost' );

You can edit wp-config.php using File Manager in cPanel or via FTP. See how to use File Manager in cPanel if you need a refresher.

Confirm the database and user exist in cPanel

Even if the config file looks correct, the database or user may have been deleted or may never have been created with the right name.

1. Log in to cPanel and go to Databases > MySQL Databases.
2. Scroll to the Current Databases table and check that the database name from your config file appears there exactly, including the prefix.
3. Scroll to the Current Users table and confirm the database username also appears there.

If either is missing, you will need to recreate it. See how to create a MySQL database in cPanel for full steps.

Confirm the user is assigned to the database with the correct privileges

A user and a database can both exist yet still be unable to connect if the user has not been linked to the database. This is a very commonly missed step.

1. In MySQL Databases, scroll to the Add User to Database section.
2. Select your database user and your database from the dropdowns, then click Add.
3. On the privileges screen, select All Privileges and click Make Changes.

If the user was already assigned, you will see the pairing listed in the Current Databases table under the database name. Check that the listed user matches the one in your config file.

Test the credentials directly with a PHP script

If everything looks correct in cPanel but the error persists, a small PHP test script gives you a clear pass or fail rather than relying on your application's error messages.

1. Create a new file called dbtest.php in your website's root folder (the same folder as wp-config.php for WordPress).
2. Paste in the following, replacing the placeholder values with your actual credentials:

<?php
$host = 'localhost';
$dbname  = 'example_mydb';
$username = 'example_myuser';
$password = 'yourpassword';

$conn = new mysqli( $host, $username, $password, $dbname );

if ( $conn->connect_error ) {
    die( 'Connection failed: ' . $conn->connect_error );
}

echo 'Connected successfully';
$conn->close();

3. Visit https://yourdomain.com/dbtest.php in your browser.
4. If you see Connected successfully, the credentials are correct and the problem lies elsewhere in your application. If you see a connection error, the message will tell you exactly what is wrong - for example a bad password or an unknown database name.

Check your PHP error logs for more detail

If the test script above does not give you enough information, or if you want to see what your application itself is reporting, your PHP error log can be very useful. It often contains more specific messages about why a connection is failing - for example a "too many connections" error or a socket problem that does not surface in the browser.

To view your PHP error log:

1. Log in to cPanel and open File Manager.
2. Navigate to the root of your website (usually public_html).
3. Look for a file called error_log. If one exists, open it and scroll to the bottom to see the most recent entries.

Alternatively, you can enable PHP error logging explicitly by adding the following lines to a .htaccess file in your site root, or to a php.ini file in the same location:

php_flag log_errors on
php_value error_log /home/yourusername/public_html/error_log

Replace yourusername with your actual cPanel username. Once you have reviewed the log, remove or disable these lines.

Check whether the MySQL connection limit is being reached

On Kualo shared hosting, each account has a limit on the number of concurrent MySQL connections it can hold open at once. All plans start at a default of 30 concurrent connections, and this can be increased up to the maximum allowed on your plan - plan limits are defined at /webhosting/resource-usage-policy.

If this limit is being hit, the error tends to be intermittent - the site works most of the time but throws the connection error under load. A constant, unrelenting error is more likely to be a credentials problem.

Hitting the connection limit is usually a symptom of an underlying issue rather than a problem solved by simply raising the number. Common root causes include:

• No page caching, so every visitor triggers fresh database queries.
• A misconfigured or disabled caching plugin.
• A vulnerable or publicly exposed endpoint being hammered by bots.

If you suspect the connection limit is involved, please contact our support team. We can review your account's resource usage, help identify the root cause, and advise on or apply a limit increase up to your plan's maximum. Reducing unnecessary database load through caching is usually the most effective fix - see configuring LiteSpeed Cache with WordPress and understanding and reducing database query load in WordPress for guidance.

Check whether MySQL is temporarily unavailable

Occasionally a brief server-side issue can cause this error to appear suddenly even though your credentials are perfectly correct. If the error appeared without warning and your credentials check out, this is worth considering.

Check our status page at status.kualo.com to see whether a known incident is in progress. If there is no incident posted and the error persists, please raise a support ticket and we will investigate at the server level.

Clear your cache after resolving the error

Once you have fixed the underlying problem, you may find your site still shows the error page. LiteSpeed Cache and WordPress caching plugins can serve a cached version of the error even after the database connection is restored.

Clear your LiteSpeed Cache from the WordPress toolbar or from the LiteSpeed Cache plugin dashboard. If you are using another caching plugin, purge its cache from the plugin's settings. You may also want to clear your browser cache to make sure you are not seeing a locally cached copy.

Summary: quick checklist

• Config file uses the full prefixed database name and username.
• DB_HOST is set to localhost.
• The database exists in cPanel MySQL Databases.
• The user exists in cPanel MySQL Databases.
• The user is assigned to the database with All Privileges.
• The password in the config file matches the one set in cPanel.
• PHP error log checked for additional detail.
• No server incident is showing on the status page.
• Cache has been purged after fixing the issue.

If you have worked through all of the above and the error continues, please contact our support team with the details of what you have already tried.