"FATAL ERROR: DB connect failed" on FreePBX/FusionPBX — diagnosing MariaDB problems

The PBX boots, Asterisk runs, but the GUI throws FATAL ERROR: DB Connection Failed or MySQL connect ERROR, or the SQL backend won't load. Underneath it's almost always one of four MariaDB issues. This article diagnoses them.

Quickly — is MariaDB running?

systemctl status mariadb     # or mysqld on older distros
journalctl -u mariadb --since "1 hour ago"

If it's stopped or crashed, that's your starting point. Skip to the relevant section below depending on the error in the journal.

Issue 1 — MariaDB won't start

Check the journal first. Common causes:

• Disk is full. Look for "no space left on device" or "InnoDB: Error: trying to extend a tablespace." Free up disk and start it. See Disk full cleanup.
• InnoDB corruption: "Database page corruption" or "ibdata1" errors. Recovery mode:

  # /etc/my.cnf or /etc/mysql/mariadb.conf.d/50-server.cnf
  [mysqld]
  innodb_force_recovery=1

  Start the daemon, dump the databases, drop, recreate, reload. Increase the recovery level up to 6 if needed, but 6 is read-only.
• Permission errors on the data dir. After a restore or migration, ownership can be wrong. chown -R mysql:mysql /var/lib/mysql and retry.

Issue 2 — "Too many connections"

MariaDB's default max_connections is often 151, which a busy PBX can exhaust during a heavy upgrade or a cron-driven mass operation. The PBX GUI shows "DB connect failed"; Asterisk shows realtime DB lookups failing.

# Check current max
mysql -e "SHOW VARIABLES LIKE 'max_connections';"
# Check current active
mysql -e "SHOW STATUS LIKE 'Threads_connected';"
# Check who's holding connections
mysql -e "SHOW FULL PROCESSLIST;" | less

Two fixes:

• Short-term:raise the limit.

  [mysqld]
  max_connections = 400

  Restart MariaDB. Costs a few MB of RAM per allocated connection slot; budget accordingly.
• Long-term: find the culprit. PHP apps that don't close connections, an Asterisk realtime config that opens too many sockets, a cron script run too frequently. Fix at the source.

Issue 3 — "Access denied for user"

The PBX's credentials don't match MariaDB's records. Causes:

• You changed the MariaDB root password but didn't update the PBX config files.
• A restore from backup overwrote the mysql.user table with stale entries.
• A failed module install changed credentials.

The PBX uses these credentials, depending on flavour:

• FreePBX: /etc/freepbx.conf and /etc/asterisk/cdr_mysql.conf. The PHP file sets $amp_conf['AMPDBUSER'] and $amp_conf['AMPDBPASS'].
• FusionPBX: /etc/fusionpbx/config.conf. The database.0.password line.

Match what's in the config with what MariaDB has:

# MariaDB-side
mysql -u root -p
> SELECT User, Host FROM mysql.user;
> SET PASSWORD FOR 'asteriskuser'@'localhost' = PASSWORD('new_password');
> FLUSH PRIVILEGES;

Then update the PBX config to match.

Issue 4 — FreePBX framework can't load its DB

Symptom: the GUI shows "DB Error: connection failed" before even prompting for login. The Asterisk side may still be running calls, because Asterisk talks to MariaDB through its own config and may have cached credentials.

Sanity check from CLI:

# Read the credentials FreePBX expects
grep -i ampdb /etc/freepbx.conf

# Try connecting with those exact credentials
mysql -u <user> -p<pass> -h localhost <dbname>

If you can connect manually, the PHP-side connection logic is the problem — typically a missing PHP MySQLi or PDO extension after a PHP upgrade. Install/enable the matching extension:

# RPM-based
dnf install php-mysqlnd
systemctl restart httpd

# Debian-based
apt install php8.1-mysql
systemctl restart apache2

FusionPBX-specific: connection.failed on sip_profile_setting

FusionPBX talks to PostgreSQL or MariaDB depending on install. If your install uses PostgreSQL and you see SQL errors about sip_profile_setting_uuid, that's almost always:

• PostgreSQL didn't start. systemctl status postgresql.
• pg_hba.conf changed. Connections from the FusionPBX user got revoked.
• Disk full on the partition holding /var/lib/pgsql.

Prevention

• Monitor disk on /var. The single most common DB failure is "InnoDB couldn't extend the tablespace because the disk is full." Set up Netdata or a simple cron alert. See Netdata quickstart.
• Back up the DB separately from the VM snapshot. mysqldump --all-databases nightly to off-host storage. Restore from this is much faster than a full VM rollback when only the DB is the problem.
• Keep PHP and MariaDB versions matched to FreePBX's tested versions — running PHP 8.2 when FreePBX only certifies up to 8.1 causes intermittent weirdness.
• Set max_connections higher than you think — RAM is cheap, "DB connect failed" at 2am is not.