Common add-on installation errors and how to fix them

Most add-on installs fail for one of a handful of reasons, and XenForo's error message usually names it. Find the message you are seeing below. Each section explains what it means and how to fix it. If you have not installed an add-on before, start with How to install a XenForo add-on.

The add-on does not appear in the list

You uploaded the files, but the add-on is not under Installable add-ons in Add-ons. XenForo cannot see it where it is.

• The upload folder was uploaded too. The files must end up at src/addons/DC/… inside your XenForo root, not at upload/src/addons/DC/…. Move the contents up one level, or upload again.
• The wrong folder was used as the root. Your XenForo root is the folder that holds admin.php and the src folder. Some hosts keep it inside public_html, others in a subfolder such as forum.
• It is already installed. Look under Installed add-ons and Upgradeable add-ons too. A newer version of an installed add-on shows up as an upgrade.

"This add-on is already installed. Please upgrade it instead."

You have an older version installed, so XenForo wants an upgrade, not a fresh install. Upload the new files over the old ones and click Upgrade. Your settings and data are kept. See How to upgrade an add-on.

"… requires …" or "may not meet the minimum requirements"

An add-on can require a XenForo version, a PHP version, a PHP extension or another add-on. When something is missing, XenForo stops with a message such as:

• {Add-on} requires {product}.
• Cannot proceed with installation/upgrade of {add-on} because it may not meet the minimum requirements.

The product named is what you need:

• A XenForo version, such as XenForo 2.3.0+: this build is for a newer XenForo. Upgrade XenForo, or check the Version History tab on the add-on's product page for an older build that supports your version. Reading version numbers explains how to pick one.
• A PHP version: ask your host to move your site to that PHP version or newer. Find your PHP version.
• Another add-on: install and enable that one first. A required add-on that is installed but disabled counts as missing. Add-ons that need another add-on first.

Missing files or files with unexpected contents

Each add-on ships with a list of its files and what each should contain. Before installing, XenForo compares the files on your server with that list. You may see:

• This add-on cannot be installed/upgraded because the following files are missing: …
• This add-on contains … files which have unexpected contents.
• The add-on files do not appear to be from the correct version. Please re-upload the correct files.

All three mean the upload did not complete, or files from two different versions got mixed. Upload the whole contents of the upload folder again, allow overwriting, and retry. FTP programs sometimes skip files silently when a transfer drops. The file health check lists exactly which files are affected.

"Install/upgrade from archive" does not work

Installing from a zip file is switched off until you add this line to src/config.php:

$config['enableAddOnArchiveInstaller'] = true;

It also needs PHP's ZipArchive support, and the web server must be able to write to your forum's folders. If your host does not allow that, the archive installer fails even with the line added. Use the upload method from the install guide instead. It needs neither.

The progress page stops or times out

Installs and upgrades run in steps, and on a large forum a step can take longer than your server allows for a web request. If the progress page stops, or shows Oops! We ran into some problems, do not start over from scratch:

1. Check Logs > Server error log for the actual error. How to read it.
2. If it was a timeout, run the same install or upgrade from the command line, where there is no time limit. The commands are here.

Tip: If the whole site shows an error after installing, rather than just the progress page, go to Site down after installing an add-on?

Still stuck? Open a support ticket with the exact error message, your XenForo version and the add-on version you are installing. Add the matching entry from the server error log if there is one.