Use the file health check to find missing or changed files

When an upload is interrupted, a file can be missing or cut short, and the add-on then fails in strange ways: a button that does nothing, a page that errors, an upgrade that refuses to run. XenForo's file health check finds these problems in a minute. It compares every file of XenForo and your add-ons with the list of files each one shipped with, and reports anything missing or changed.

How the check works

Every XenForo release, and every properly packaged add-on including ours, contains a hashes.json file. It lists each file in the package with a fingerprint of its contents. The file health check reads those lists, looks at the files on your server, and reports two kinds of problem:

• Missing: the file should be there but is not.
• Unexpected contents: the file is there, but it is not the file that shipped. It may be a partial upload, a file from a different version, or a file someone edited.

Run it from the Admin CP

1. Open Tools > File health check.
2. Click Proceed. The check runs in the background and takes a minute or two on most forums.
3. The results table shows each check with its Check state, the number of Missing files, the number with Unexpected contents, and the Total checked. Click Results on a row to see the list of affected files.

The file paths tell you where the problem is. Anything under src/addons/DC/… or js/DC/… belongs to a D.C Style add-on, and the folder name after DC/ tells you which one.

Run it from the command line

If you have SSH access, you can run the same check with:

php cmd.php xf:file-check

To check one add-on only, pass its ID with --addon:

php cmd.php xf:file-check --addon=DC/Thumbnail

Run it from your XenForo root, the folder that holds cmd.php. More commands are in Install, upgrade and rebuild add-ons from the command line.

Fixing what it finds

For problems in an add-on's files, the fix is nearly always the same:

1. Download the zip for the version you have installed. The version is listed next to the add-on in Add-ons.
2. Upload the whole contents of its upload folder again, and allow your FTP program to overwrite existing files.
3. Run the file health check again. It should now report nothing for that add-on.

Tip: If you upload with FTP, switch the transfer mode to binary (or "auto") and check your FTP program's log for failed transfers. Files that fail to transfer are skipped quietly more often than you would think.

For problems in XenForo's own files, under src/XF/, upload the matching XenForo release from your XenForo customer area in the same way.

Results you can ignore

Not every result is a problem:

• Files you edited on purpose show as unexpected contents. XenForo's own advice is that you may ignore this if you edited the files yourself. If you did not, investigate, because a file changed without your knowledge can be a sign of corruption or tampering.
• An add-on without a hashes file cannot be checked. XenForo says so: The hashes.json file for this add-on is missing so no file health check can be performed. That is a packaging choice by the add-on's developer, not an error on your forum.

Warning: If files you never touched suddenly show unexpected contents, and especially if they are XenForo's own files, treat it as a possible security issue. Read the XenForo security checklist and restore clean files from the official downloads.

When to run it

• After every install or upgrade that behaves oddly.
• When an install stops with a missing-files error.
• When buttons stop working after an upgrade. Missing JavaScript files are a classic cause. See Buttons or pop-ups not working.

Still stuck? Open a support ticket with a screenshot of the file health check results and the add-on version you have installed.