Update Incomplete Errors

Problem

This information only applies to self-hosted WHMCS installations. WHMCS Cloud updates WHMCS for you automatically.

An automatic update stopped before it finished, and an Update Incomplete page displays in the Admin Area:

Update Incomplete

An automatic update stopped while it was replacing the WHMCS files, so it cannot finish on its own. Upload the complete files for this release, including the install directory, then open install/install.php to finish the upgrade. If you have already restored or uploaded a complete set of files, delete the .whmcs-relocating file from the WHMCS root directory.

Clients see a Down for Maintenance notice until you finish the upgrade.

Cause

An automatic update replaces your WHMCS files in two stages. First it replaces the files. Then it updates the database. Before it replaces the first file, WHMCS creates a temporary .whmcs-relocating file in the WHMCS root directory.

If something stops the update during the file replacement stage:

  • The .whmcs-relocating file stays in place, and some new files may be missing.
  • WHMCS does not update your database for the new version while that file exists.
  • WHMCS displays your Maintenance Message, or a Down for Maintenance (Err 3) error. It does so until the update fails or one hour passes. After that, the Update Incomplete page displays when you open the Admin Area.

Solution

This troubleshooting information only applies to self-hosted WHMCS installations.

To finish the upgrade, use the method that matches the state of your files.

Upload the Release Files

If you do not know which files the update replaced, upload the release files:

  1. Download the full release for the version that you were updating to.
  2. Upload the release files to your WHMCS installation’s directory, replacing the existing files. Include the install directory.
  3. Go to the /install/install.php file in your WHMCS installation’s directory. For example, www.example.com/whmcs/install/install.php.
  4. Agree to the End User License Agreement.
  5. Click Continue.
  6. Back up the WHMCS MySQL® database.
  7. Click I have a backup, start the upgrade.
  8. Delete the install directory from your server.
  9. Check that the version in Configuration () > System Health is the version that you were updating to.
For more information about this process, see Update in the Browser.

Delete the Relocating File

If you already restored or uploaded all the files for one version, delete the .whmcs-relocating file:

  1. Delete the .whmcs-relocating file from your WHMCS installation’s root directory.
  2. Go to the Admin Area.
  3. Check that the version in Configuration () > System Health is correct.
  • Check the WHMCS version in a backup before you restore it over a partial update. Files and a database on different versions produce a Down for Maintenance (Err 2) error.
  • WHMCS cannot check whether your files are complete. If you delete this file while files are still missing, later updates may fail.
troubleshooting troubleshooting-article updates

Last modified: 2026 October 20