Refused Installation Errors

Problem

This information only applies to self-hosted WHMCS installations. WHMCS Cloud handles the installation and initial configuration process for you automatically.

You run install.php to start a new installation. The installation process stops and you see one of the following messages:

The system detected an existing WHMCS installation. A new installation cannot run while the configuration.php file connects to it.

The configuration.php file contains database details, but the system could not connect to that database.

The installation process does not continue to the license key or database details steps. Clicking Begin Installation returns you to the start of the process.

To confirm which message the installation process showed, check the /install/log/installer.log file.

Cause

WHMCS protects an existing installation from a new one that would replace it. Before the installation process continues, it reads the configuration.php file in the root WHMCS directory. It then checks the database that the file names. It returns one of these messages if either of the following statements is true:

  • The database contains a WHMCS installation with an admin account. A new installation would replace the configuration.php file. It would discard the credit card encryption hash and leave your data unreadable.
  • The system cannot connect to the database and check its contents. It refuses the new installation. The database may belong to a live installation that is temporarily down.

Solution

The solution depends on whether the database contains a WHMCS installation or is unreachable.

The database contains a WHMCS installation.

To perform a new installation on a different database:

  1. Back up the configuration.php file. It contains the credit card encryption hash that decrypts your stored data.
  2. Change the database details in the configuration.php file to the details for the new database.
  3. Restart the installation process at install.php.

To upgrade the existing installation instead, continue on the Upgrade Your Installation page.

For more information, see Update in the Browser and Encryption Hash Errors.

The database is unreachable.

First, determine whether the database belongs to an existing installation:

  1. Check that the database server is running.
  2. Check that the database host, port, username, password, and database name in the configuration.php file are correct.
  3. Reload the page.
If those details belong to an existing installation, do not continue. Restore access to that database instead. A new installation replaces the configuration.php file and discards your credit card encryption hash.

To start a new installation when you no longer need that database:

  1. Back up the configuration.php file. It contains the credit card encryption hash that decrypts your stored data.
  2. Empty the configuration.php file.
  3. Restart the installation process at install.php.
troubleshooting troubleshooting-article installation configuration-php

Last modified: 2026 October 20