The "Could not connect to database" error means that Joomla 6 cannot establish a connection to the MySQL or MariaDB database.

Joomla stores almost all website data in the database, including articles, users, extensions, configuration settings, and menu items. If the database connection fails, the website usually becomes unavailable and the Administrator area may also stop working.

This error is usually caused by one of the following:

• incorrect database credentials
• wrong database hostname
• missing database permissions
• unavailable MySQL or MariaDB server
• incorrect PHP configuration
• server-side restrictions

This guide explains how to diagnose and fix the problem step by step.

1. Check the Joomla database configuration

The first place to check is the Joomla configuration file.

The file is located in the Joomla root directory:

/configuration.php

Open it using FTP, SSH, or your hosting file manager.

Look for these database settings:

public $host = 'localhost';
public $user = 'database_username';
public $password = 'database_password';
public $db = 'database_name';

Verify that each value matches the database information provided by your hosting provider.

Check the database hostname

The most common value is:

localhost

However, some hosting providers use a separate database server, for example:

mysql.example.com
db123.hosting-provider.com

If the hostname is incorrect, Joomla cannot connect even when the username and password are correct.

The correct database hostname can usually be found in:

• your hosting control panel
• database management section
• hosting setup documentation

2. Verify the database username and password

A very common cause of this error is a changed database password.

For example, if you changed the database password in your hosting control panel but did not update Joomla, the values no longer match.

Check:

public $user = 'database_username';
public $password = 'database_password';

Make sure:

• the database user exists
• the password is correct
• there are no extra spaces before or after the values

If you are unsure about the password, reset it in your hosting control panel and update configuration.php.

3. Test the database using phpMyAdmin

To determine whether the problem is Joomla or the database server, test the database directly.

Log in to your hosting control panel and open:

phpMyAdmin

Try to open the Joomla database.

If phpMyAdmin works:

• the database server is running
• the database exists
• the problem is likely inside Joomla configuration

If phpMyAdmin cannot connect:

• the database server may be unavailable
• the database user may have incorrect permissions
• the hosting provider may have an issue

4. Check database user permissions

The database user configured in Joomla must have full access to the Joomla database.

In your hosting control panel, open the database management section and verify that:

• the user is assigned to the correct database
• the user has permission to read and write data

Joomla requires permissions for operations such as:

• SELECT
• INSERT
• UPDATE
• DELETE
• CREATE
• ALTER
• INDEX

A user with limited permissions may allow some operations but fail when Joomla tries to update content, install extensions, or save configuration changes.

5. Check MySQL or MariaDB server availability

If you manage your own VPS or dedicated server, verify that the database service is running.

For MySQL:

systemctl status mysql

For MariaDB:

systemctl status mariadb

If the service is stopped, restart it:

systemctl restart mysql

or:

systemctl restart mariadb

Also check database server logs:

/var/log/mysql/error.log

or:

/var/log/mariadb/mariadb.log

A database server that is overloaded, crashed, or out of disk space can cause Joomla connection failures.

6. Verify Joomla 6 PHP requirements

Joomla 6 requires a supported PHP environment.

If your hosting provider recently changed PHP versions, verify that the active PHP version is compatible with Joomla 6.

Check the PHP version in your hosting control panel.

Also verify that required PHP extensions are enabled.

The most important database-related extensions are:

mysqli
PDO
pdo_mysql

Without a working MySQL PHP driver, Joomla cannot communicate with the database.

On shared hosting, ask your hosting provider to confirm that these extensions are enabled.

7. Clear Joomla cache manually

A database connection error normally prevents access to the Joomla Administrator area, so cache cannot be cleared from the control panel.

You can remove cached files manually using FTP or your hosting file manager.

Open:

/cache/

Delete the contents of this directory.

Keep:

/cache/index.html

If your installation contains the administrator cache directory, also clear:

/administrator/cache/

Keep:

/administrator/cache/index.html

Clearing cache does not usually fix a real database connection problem, but it removes old cached data after configuration changes and is a safe troubleshooting step.

8. Enable Joomla debugging

If the problem is still not clear, enable Joomla error reporting.

Open:

/configuration.php

Find:

public $debug = false;
public $error_reporting = 'default';

Change it to:

public $debug = true;
public $error_reporting = 'maximum';

Reload the website.

Joomla may now display a more detailed error message.

Common database errors include:

Access denied for user

Example:

Access denied for user 'username'@'localhost'

Cause:

• wrong password
• incorrect username
• missing permissions

Solution:

• verify the database user
• reset the password
• update configuration.php

Unknown database

Example:

Unknown database 'database_name'

Cause:

• incorrect database name
• deleted database

Solution:

Check:

public $db = 'database_name';

and verify that the database exists in your hosting panel.

Connection refused

Example:

Connection refused

Cause:

• MySQL/MariaDB service is down
• incorrect database hostname
• firewall restrictions

Solution:

Check the database server status or contact your hosting provider.

9. Check server error logs

If Joomla does not display enough information, check the server logs.

Common locations:

Apache:

/var/log/apache2/error.log

Nginx:

/var/log/nginx/error.log

PHP errors may also be available in your hosting control panel under:

• Error Logs
• PHP Logs
• Server Logs

Look for messages related to:

• MySQL
• mysqli
• PDO
• connection timeout
• permission denied

10. Check file permissions

Incorrect file permissions usually do not directly cause database connection errors, but they can appear after migrations, restores, or server changes.

Recommended Joomla permissions are usually:

Directories:

755

Files:

644

The Joomla configuration file should not be writable by everyone.

Check:

/configuration.php

and make sure it has appropriate permissions.

11. When the problem is caused by hosting

If all Joomla settings are correct and the database still cannot be reached, the problem is likely outside Joomla.

Possible causes include:

• MySQL server outage
• database server overload
• blocked database connections
• corrupted database tables
• exceeded hosting limits
• firewall restrictions

When contacting your hosting provider, provide:

• Joomla version
• PHP version
• database type (MySQL or MariaDB)
• exact error message
• time when the problem started

This allows the hosting support team to identify the issue faster.

Joomla 6 Database Connection Troubleshooting Checklist

Before contacting support, verify the following:

☐ /configuration.php contains correct database credentials
☐ Database hostname is correct
☐ Database exists
☐ Database user has full permissions
☐ phpMyAdmin can access the database
☐ PHP MySQL extensions are enabled
☐ MySQL/MariaDB service is running
☐ Joomla cache directories were cleared
☐ Debug mode was enabled and error message checked
☐ Server logs were reviewed

Conclusion

The Joomla 6 "Could not connect to database" error is usually caused by incorrect database settings or a problem with the database server.

Start with the simplest checks:

1. Verify /configuration.php
2. Test the database in phpMyAdmin
3. Check database permissions
4. Confirm PHP and MySQL compatibility
5. Review server logs if the problem continues

Following these steps will usually identify whether the issue is inside Joomla or on the hosting server.