3 major reasons and other common issues for your upgrade failing.

So after releasing beta 1 of V20 and Update 9 we’ve already had quite a number of upgrades - enough to be statistically significant. And the results are interesting. These are the top reasons for an upgrade to not start:

Number #1 - Insufficient cores - 2+ required

The number one reason for an upgrade failure is the machine not having 2 or more cores. To run 3CX properly, you need 2 cores. 3CX is a real time application that is processing audio - and in some cases video - and cannot afford to have the CPU taken away, even for just a few seconds. This will cause audio issues, provide a bad experience and ultimately affect our brand name. If the machine does not have enough cores, the upgrade will not fail, it will just not run. You will need to upgrade the machine to 2 cores first.

Number #2 - Source list has been edited

The second reason your upgrade will fail is due to the installation of unsupported packages on the ISO. In this case we cannot forecast the outcome of the upgrade so we will not run the upgrade. The only way to upgrade in this case is to do a backup and restore. Some example source lists we found are osconfig_managed_7a718e6aad.list, busylight.list, mysql.list, hetzner-mirror.list.

Number #3 - Not enough RAM - 2 Gig required

Besides real time processing of audio and video, 3CX also hosts a web server with full Web Client. This takes some memory. 1 Gig is nothing these days. To run a mission critical communication system 2 Gig is really the minimum required. So you’ll need to upgrade your system to have sufficient memory.

Environments tested

  • Installation based on the 3CX ISO without any modifications on bare bones and supported virtual environments.
  • Leading cloud platform providers
    • Google Cloud (Compute Engine)
    • Amazon AWS (+LightSail)
    • DigitalOcean
    • Microsoft Azure
    • Vultr

Process

So what happens when you upgrade? Your system will upgrade from Debian 10 to Debian 11 and then to 12. Depending on the specs of the machine, the size of your 3CX installation, your internet connection as well as whether the system is up to date, the upgrade can take anything from 10-15 minutes right up to an hour or more. Upon successful upgrade, your system will reboot. An email will be sent with the result of the upgrade to the system admin. The email will inform you if the upgrade was aborted, failed or successful.

Important

  • Do not attempt to interact with the system/instance during the upgrade process.
  • Take a full backup of 3CX and store it outside of the instance
  • If possible take a full snapshot of the VM
  • During the upgrade 3CX will be unavailable so make sure you schedule it outside office hours

Other common issues

  • Manually added/removed repositories.
  • Manually installed packages, causing dependency issues.
  • Remote administration or monitoring tools that could interfere with the upgrade process (e.g locking APT, attempting to restart services)
  • Altered locale or TZdata
  • Modified/broken configuration files/packages
  • Tampered root certificates
  • Restricted internet access
  • Users interacting with the system while the upgrade is running.

What to do if upgrade fails

If the upgrade fails, check system requirements, fix and run again. If it still fails, you will need to do a full backup and restore to a new system.

Requirements once again

  • At least 2vCPU, 2GB of ram and 5GB of free disk space
  • No third party source files under /etc/apt/sources.list.d/ (other than 3CX and the provider agents)
  • No third party software installed
  • Uninterrupted connectivity to repo.3cx.com and deb.debian.org

Note: We gather logs solely for debugging purposes which are deleted shortly after an upgrade is completed. Logs of failed upgrades are reviewed by our engineers to determine potential pitfalls and improve the upgrade process.

Summary

Running a dedicated instance requires a correctly sized instance. For very small installs (less than 5-10 extensions) consider using 3CX SMB or 3CX FREE. If the customer really needs a dedicated system then they need to understand that the specs will need to be aligned with the up to date and absolutely reasonable requirements. Happy Upgrading!

Follow Us

Let us know what you think in the Forum. Hit the follow button on our X and LinkedIn pages to stay-up-to date on further developments.