How to Fix a Database Connection Error During Joomla Installation
A database connection error during Joomla installation means the installer cannot establish the database session it needs with the values or environment currently provided. Treat the four connection values separately—database type, host, username/password, and database name—then verify that the database service accepts that user from the web server.
Use the values from your database service, not your Joomla login
On Setup Database Connection, Joomla needs database credentials. These are separate from the Super User account created for Joomla Administrator. Record the exact database host, database name, database username, and database password from your hosting panel or database administrator.
1. Verify the database type and PHP driver
Select the database type that matches the service and PHP driver available on the server. Joomla's current technical requirements support MySQL/MariaDB and PostgreSQL families, with the appropriate PHP database driver. If the required PHP driver is missing, correct the PHP environment; changing the database password will not install a missing driver.
2. Verify the database host
localhost is common on shared hosting, but it is not universal. Some providers use a dedicated hostname or address. Copy the value the provider specifies. If the database is remote, confirm that it accepts connections from the Joomla web server and that any firewall or allow-list permits that source.
Do not automatically replace localhost with 127.0.0.1 or the reverse: those can use different connection mechanisms or server policies. Use the host's documented value.
3. Verify the full database username and password
Shared hosting often prefixes database usernames. The value displayed by the hosting panel is authoritative. Re-enter the password carefully or reset the database user's password if necessary, then update the installer with the new value. Do not use the hosting-control-panel password or Joomla Super User password unless that is coincidentally the database password you explicitly created.
4. Verify the database name exists
Manual Joomla installation normally requires a database to be created first. Confirm that the database exists and use its complete displayed name, including any account prefix. A valid database account can still fail when pointed at a nonexistent or inaccessible database.
5. Confirm the database service is running and reachable
Joomla's documentation notes that an unavailable MySQL/MariaDB service can produce connection failures even when credentials have not changed. Check the provider's service status or ask the server administrator whether the database server is running. For a remote database, also test DNS/network reachability from the web-hosting environment.
6. Distinguish authentication from authorization
If the server rejects the username/password before a session is established, fix credentials, host permissions, or connectivity. If Joomla connects but then fails to create tables, indexes, or other schema objects, the connection itself worked and the likely problem is database privileges. Make sure the Joomla database user is assigned to the intended database with the privileges required to create and maintain Joomla's schema.
7. Check whether the user is allowed from this host
MySQL/MariaDB accounts can be scoped by both username and client host. A database account that works from a local database console or another server may not be permitted from the web server running Joomla. On managed hosting, ask the provider to verify that the database user is authorized for the Joomla site's connection source.
8. Use the error wording to narrow the failure
- Access denied: usually username/password or account-host authorization.
- Unknown host / name resolution: database hostname or DNS problem.
- Connection refused / timeout: service, port, firewall, or network path.
- Unknown database: database name does not exist or is not visible to the account.
- Could not connect to the database: re-check host, user, password, service availability, and provider-specific connection details.
- Permission denied while creating tables: connection succeeded; correct database privileges.
9. Retest with one controlled change at a time
After correcting a value, retry the database step. Avoid changing host, username, password, and database name simultaneously unless you already know all four were wrong; controlled changes make the successful fix clear. If the installer still fails, provide the hosting provider with the exact error text, timestamp, database hostname, and database username—but never send the password in an ordinary support message unless the provider gives you a secure method.
When the connection works but installation still fails
A successful connection moves troubleshooting to schema creation, database privileges, SQL compatibility, or another installation stage. Do not keep rotating valid credentials after Joomla has already demonstrated that it can connect. Investigate the new error at the layer it identifies.
Need More Help with Joomla?
Still having trouble? Open a support ticket with QuantaCade Support and we'll be happy to help where we can.
Support priority is given to QuantaCade products, services, and customers. However, we're also happy to assist fellow Joomla users with general Joomla questions and troubleshooting when possible.
QuantaCade is an independent Joomla extension developer and is not official Joomla support. Some issues involving third-party extensions, hosting environments, server configurations, or other systems outside our development control may be beyond what we're able to resolve.