Skip to main content
Submit a request

Database connection errors

Maxim Tsitsejev
Updated

Applies to: All plans.

A database connection error means your website or app loaded, but could not reach its MySQL database. Almost always the cause is the wrong database details in your app's configuration file, or a database user that has lost its privileges. Your files and your data are almost certainly still there — only the link between the app and the database is broken. This guide shows you where to check the credentials and privileges in cPanel.

Using WordPress? If your error reads exactly "Error establishing a database connection", follow the dedicated guide: Fixing "Error establishing a database connection". This article covers database errors more generally (WordPress, Joomla, a custom app, or a command-line connection).

Symptoms

  • Your site shows a database error such as "Could not connect to database", "Connection refused", "Access denied for user", or "Unknown database".
  • An app installer or migration fails at the "connect to database" step.
  • A page that needs the database is blank or errors, while static pages still load.
  • The error appeared right after a migration, a password change, or an edit to a config file.

Common causes (most likely first)

  1. Wrong credentials in your app's config file — the database name, user, password or host in the config no longer match what exists in cPanel. This is by far the most common cause, especially after moving a site or resetting a password.
  2. The database user has no privileges on that database — the user exists but is no longer attached to the database with full permissions.
  3. The wrong database host — on our servers the host is always localhost, not a hostname or an IP address. A remote host or 127.0.0.1 will fail.
  4. The account is over its resource limits — under heavy load MySQL can briefly refuse new connections (you may see "max_user_connections"). This usually clears on its own.

Quick fixes

1. Find your real database details in cPanel

  1. Log in to cPanel: open your service in the client area -> Services -> My Services, then choose Log in to cPanel.
  2. Go to cPanel -> Databases -> MySQL Databases.
  3. Under Current Databases, note the exact database name. Under Current Users, note the exact username. Both names include your cPanel account prefix (for example acct_app), so copy them carefully.
  4. If you are not sure of the password, reset it: find the user under Current Users, choose Change Password, and set a fresh one. Note the new password.

Result: You now have the exact database name, username and password that really exist on the server.

2. Match them in your app's config

  1. Open cPanel -> Files -> File Manager and go to your site's folder (usually public_html for the main domain).
  2. Edit your app's configuration file (for example wp-config.php for WordPress, configuration.php for Joomla, or .env for a custom app).
  3. Make the database name, user and password match the values from step 1 exactly, and set the database host to localhost.
  4. Save the file and reload your site.

Result: When the four values match a real database, user and host, the connection error clears.

3. Confirm the user is attached with full privileges

  1. In cPanel -> Databases -> MySQL Databases, scroll to Add User To Database.
  2. Pick your database user and your database, then click Add.
  3. On the privileges screen, tick ALL PRIVILEGES, then Make Changes.

Result: The user can now read and write the database. Reload your site to confirm.

If that did not work

  • Test the login directly in phpMyAdmin. Open cPanel -> Databases -> phpMyAdmin and try to open the database. If it will not open with your database user and password, the credentials are still wrong — repeat steps 1 and 2. See How to use phpMyAdmin.
  • Check the database actually exists. An "Unknown database" error means the name in your config does not exist in MySQL Databases. Create it (or restore it) and re-point your config — see How to create and manage a MySQL database.
  • Rule out a resource spike. If the error only appears under traffic, you may be hitting your plan's limits — see MySQL slow or using high CPU.
  • Restore from a backup. If the database is damaged, restore a recent copy with JetBackup — see How to restore a database.
  • Note on email: databases have nothing to do with your email. We do not host mailboxes on the hosting server, so a database error never affects your Microsoft 365 or Google Workspace mail.

Related articles

Comments

0 comments

Please sign in to leave a comment.