FreePBX upgrade failed — recovery, rollback, and how to avoid it next time

FreePBX® distro upgrades have moving parts: framework, modules, underlying OS packages, PHP, MariaDB, Asterisk itself. When one fails, the symptoms range from "amber warning in the dashboard" to "phones don't ring anymore." This article covers the common upgrade failure modes, how to recover, and the habit that prevents most of them.

Before any upgrade — the rule

Take a snapshot first. Portal → your VPS → Snapshots → New. Label it with the date and "pre-upgrade." If the upgrade goes sideways, you roll back the snapshot and the PBX is exactly where it was. See How to take a VPS snapshot.

Snapshots are fast, free, and survive even total upgrade failures. The customers who avoid upgrade-recovery tickets are the ones who snapshot first.

Common failure modes

"IONCUBE not working or not installed"

Some commercial FreePBX modules (App Manager, EPM Pro, others) ship as ionCube-encoded PHP. When PHP gets upgraded, the bundled ionCube extension can fall out of sync.

Fix:

# Re-download the matching ionCube loader for your PHP version
php -v   # note the PHP version
cd /usr/local/src
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar xzf ioncube_loaders_lin_x86-64.tar.gz
# Find your PHP version's loader
ls ioncube/ | grep $(php -r 'echo PHP_MAJOR_VERSION."_".PHP_MINOR_VERSION;')
# Copy to PHP extensions dir
PHP_EXT=$(php -i | grep ^extension_dir | awk '{print $3}')
cp ioncube/ioncube_loader_lin_X_Y.so $PHP_EXT/
# Add to PHP config
echo "zend_extension=$PHP_EXT/ioncube_loader_lin_X_Y.so" > /etc/php.d/00-ioncube.ini
# Restart web server and Asterisk
systemctl restart httpd asterisk

Replace X_Y with your PHP major.minor (e.g., 8_1).

"Source files update failed"

The PBX Upgrader pulls source tarballs from FreePBX infrastructure. If their CDN is having a moment, or if your VPS firewall is blocking outbound HTTPS, the update fails.

Check:

# Can the PBX reach the FreePBX update mirrors?
curl -I https://mirror.freepbx.org/
# Try again
fwconsole ma upgradeall

If a specific module won't upgrade, install it manually:

fwconsole ma download <module-name>
fwconsole ma install <module-name>
fwconsole reload

"High Availability Services 13.0.11..." after upgrade

The upgrade ran partway then stopped, leaving the system in an inconsistent state — Asterisk version partly upgraded, modules expecting a different version, dashboard showing errors.

The reliable recovery: roll back to your pre-upgrade snapshot. This is why we took it.

If you don't have a snapshot (please, next time):

# Force re-install of core modules
fwconsole ma install core
fwconsole ma install framework
fwconsole reload
fwconsole restart

If that doesn't clear it, open a ticket — recovering a half-upgraded PBX without a snapshot is delicate and worth having an experienced set of eyes on.

Modules disappeared from the dashboard

Usually a permission or database glitch from the upgrade:

fwconsole chown
fwconsole reload

Asterisk won't start after upgrade

Most often a dialplan syntax error introduced by an upgraded module, or a missing library.

# Watch Asterisk start and capture the error
asterisk -cvvv
# Or run it in the background with verbose logging
fwconsole start
tail -f /var/log/asterisk/full

Note the first ERROR line — that's the cause. Common culprits:

• A custom .conf file in /etc/asterisk/ that references a removed feature.
• An out-of-date third-party module that doesn't load on the new Asterisk version.
• A MariaDB connection failure (see FATAL ERROR: DB connect failed).

If you didn't snapshot — the slow recovery path

Two options:

1. Forward through the upgrade. Re-run the upgrade and fix each error as it comes up. Sometimes works; sometimes you accumulate three more problems.
2. Restore from FreePBX backup module. If you took an in-PBX backup before the upgrade (separate from VM snapshots), restore that. See FreePBX backup and restore — note that this restores PBX configuration but doesn't restore underlying OS state.

If neither works, the realistic path is a clean install on a new VPS plus a config migration. Open a ticket if you need help sequencing this.

Before the next upgrade — checklist

• Take a VPS snapshot first.
• Take a FreePBX backup separately (covers the case where you can't roll back the snapshot for some reason).
• Check the FreePBX release notes for known issues with the version you're moving to.
• Note your current FreePBX, Asterisk, PHP, and MariaDB versions in a text file. Useful if you need to debug later.
• Run the upgrade during a low-traffic window. Voice traffic during an upgrade is risky.
• Plan a 30-minute test cycle after the upgrade — registration, inbound call, outbound call, voicemail, feature codes.