FreePBX backup restore version mismatch: choose the supported migration path

Name both versions before retrying

Record the source FreePBX major version, target major version, target Asterisk version, backup-module version, archive creation time and restore phase that failed. Preserve the full warning and restore log. A browser message that says a backup is incompatible can represent an unsupported direction, a missing module handler, a malformed archive, a target dependency or a version-specific telephony conversion; do not collapse them into one generic mismatch.

Do not overwrite the source system or its only backup. Retain the original archive, its size and checksum, and create the target in an isolated maintenance context. A backup file that uploads successfully is not evidence that every module, custom file or call-flow object can be restored.

Check the loaded backup module before parsing the archive

The release/17.0 metadata listed Backup & Restore 17.0.14 on October 8, 2026 and requires Filestore 17.0.2.44 or later. Its recent changelog records security corrections affecting restore operations, backup metadata, unsafe deserialization and restricted SSH backup keys. Capture the installed Backup & Restore and Filestore versions, repository channel and signature state before attributing a restore failure to the archive's major version.

Update only through the supported module-management path and preserve the before-and-after state. Do not retry a questionable archive on production, bypass signature or dependency checks, reuse a broadly privileged remote-storage key, or grant wider filesystem access to clear an error. A version string alone does not establish that the running files were loaded correctly or that an archive and destination are trustworthy.

Use the documented upgrade direction

Sangoma documents Backup and Restore as the recommended path from FreePBX 13 to a new FreePBX 15 system and from FreePBX 13 or 14 to a new FreePBX 16 system. For FreePBX 17, there is no direct inline upgrade from an earlier major version; the supported path is a backup from the existing system restored to a newly installed 17 system. Match the actual source and target to the version-specific guide.

The FreePBX 17 FAQ explicitly says that restoring a 17 backup to 16 is not tested or supported. Do not treat cross-version restore as symmetric, and do not use a newer-production backup as a routine rollback archive for an older major version. Preserve the old system independently until target acceptance is complete.

Inspect the backup scope before blaming the target

FreePBX 15 and later moved backup ownership to individual modules and storage configuration to Filestore. The backup job can select modules and custom directories, while call recordings are not included by default. Review the job definition and confirmation screen to prove which modules and paths were present. Missing content after restore may reflect the source job, not target incompatibility.

Record any custom dialplan, AGI scripts, certificates, recordings, voicemail, endpoint provisioning data, commercial modules and operating-system files that require separate handling. Do not add broad filesystem roots to a production backup without estimating archive size, sensitive-data exposure and restore consequences.

Separate target modules and activation from archive compatibility

The FreePBX 15 and 16 migration guides install a new target, activate it, update its modules and then restore. The Version 17 FAQ recommends activating first when commercial-module data must be restored; an open-source-only target may be activated afterward. Preserve the target module and activation state before changing either.

A missing commercial entitlement, unsigned module, unavailable target version or absent module restore handler is not the same as a corrupt backup. Route each named failure to the module or licensing owner. Do not force-install a deprecated or incompatible module merely to clear the restore screen, and do not claim that activation transfers licenses without account evidence.

Treat Asterisk 22 conversion as a separate branch

FreePBX 17 currently installs Asterisk 22 by default. Sangoma documents that Asterisk 22 does not support chan_sip or the Macro dialplan application. During restore, a 17 system running Asterisk 21 or later can prompt to convert chan_sip devices and trunks to PJSIP; the FAQ says converted trunks must be thoroughly tested because provider configurations vary.

Capture whether the restore stopped for conversion, continued with conversion or was cancelled. Review custom dialplan for Macro dependencies and record the resulting PJSIP transport, port, identification, authentication and registration objects. A completed database restore does not prove that an automatically converted endpoint or trunk can register or place calls.

Use CLI restore only for the documented reason

Sangoma documents fwconsole backup --restore for FreePBX 15-plus and prefers CLI restore for very large FreePBX 17 backups that may time out in the GUI. It also documents an alternate TMPDIR when temporary storage is constrained. Use installed command help and the exact version guide; preserve output and free-space evidence.

The documented preserve options such as --ignoremodules, --skipbindport, --skipdns and --skipremotenat change what is restored. They are not generic compatibility switches. Use one only when its preserved target state is intentional, recorded and separately validated. CLI removes a confirmation step; it does not make an unsupported downgrade supported.

Accept the migrated system as a new deployment

After the restore completes, compare module status, extension and trunk counts, routes, schedules, prompts, certificates, NAT and bind settings, provisioning ownership and required custom files against the source inventory. Then run bounded tests for internal calling, inbound and outbound routes, caller identity, DTMF, transfer, voicemail, two-way audio and hangup. Use the provider-approved emergency procedure only after location and callback data are verified.

Keep the old system isolated but recoverable until the target passes acceptance. Record every conversion, skipped module and manual repair. No PBX, backup, archive, module, restore, license, conversion, endpoint, trunk or live-call behavior was tested for this guide.

Do not let a version mismatch hide a custody or handler failure

Before retrying, verify the original archive hash and custody, the source job scope and manifest, and the target module that owns the failed restore item. Current FreePBX advisories require an updated Backup & Restore module before import; a CLI retry or forced module install does not authenticate an archive or create a missing module restore handler.

Branch when the restore finishes but content is absent

If the version direction is supported and the transaction completes, continue with the missing settings or files diagnostic to distinguish source job scope, archive manifest, target handler, file extraction, generated configuration and loaded runtime.

Check Filestore handler versions before blaming the archive

Record the installed Backup & Restore and Filestore versions, destination type and transfer evidence. The missing-artifact workflow determines whether the intended bytes ever reached the recovery path before archive-version diagnosis.