Attachment Integrity Check (CLI) 2026-08-22
- Author MentaL
- Creation date
Is it safe to run on a live forum?
The scan is read-only and safe to run at any time. It never writes to the database. Deleting requires a second run with an explicit --delete flag, and is protected by several guards described in the resource description. Take a database backup before using --delete regardless.
Will this delete my posts or threads?
No. It only ever touches xf_attachment and xf_attachment_data rows. Posts, threads and their text are never modified. An
It says thousands of attachments are MISSING. Should I delete them?
Almost certainly not — check your storage first. A partial mount, wrong credentials or a bad prefix looks exactly like mass data loss from the script's point of view. That is why the ratio guard refuses plans over 20%. Confirm your attachment storage is fully mounted and readable before treating the result as real.
What is the difference between MISSING and RELINK?
RELINK means the file is still there under a different key and its md5 matches, so the data is intact and only the database pointer is stale. MISSING means there is nothing recoverable. The script never relinks on a filename match alone — the bytes must hash correctly, otherwise a recycled data_id would attach the wrong file to somebody's post.
My scan found almost nothing but I know I lost content. Where is it?
Run --orphans. A normal scan walks the database, so it can only find damage on the storage side. If your database was rolled back instead, the rows for newer uploads no longer exist and their files are stranded in storage with nothing pointing at them. The orphans mode finds those and buckets them by file date, which shows you the shape of the gap.
Does it work with S3 / R2 / remote storage?
Yes. It goes through XenForo's own abstracted filesystem, so whatever adapter your forum uses works. Always pass --index on remote storage — without it, every row is a separate network round-trip.
Do I need to install an add-on?
No. It is a single standalone PHP file placed in your forum root, run from the command line. Delete it when you are finished if you prefer.
Why does it need file_key rather than file_hash?
Because that is what XenForo actually uses to build the stored path. They are both 32-character hex strings and are easy to mix up. The script aborts on schemas without the column rather than deriving wrong paths.
The scan is read-only and safe to run at any time. It never writes to the database. Deleting requires a second run with an explicit --delete flag, and is protected by several guards described in the resource description. Take a database backup before using --delete regardless.
Will this delete my posts or threads?
No. It only ever touches xf_attachment and xf_attachment_data rows. Posts, threads and their text are never modified. An
[ATTACH] tag pointing at an attachment that no longer exists simply renders as nothing.It says thousands of attachments are MISSING. Should I delete them?
Almost certainly not — check your storage first. A partial mount, wrong credentials or a bad prefix looks exactly like mass data loss from the script's point of view. That is why the ratio guard refuses plans over 20%. Confirm your attachment storage is fully mounted and readable before treating the result as real.
What is the difference between MISSING and RELINK?
RELINK means the file is still there under a different key and its md5 matches, so the data is intact and only the database pointer is stale. MISSING means there is nothing recoverable. The script never relinks on a filename match alone — the bytes must hash correctly, otherwise a recycled data_id would attach the wrong file to somebody's post.
My scan found almost nothing but I know I lost content. Where is it?
Run --orphans. A normal scan walks the database, so it can only find damage on the storage side. If your database was rolled back instead, the rows for newer uploads no longer exist and their files are stranded in storage with nothing pointing at them. The orphans mode finds those and buckets them by file date, which shows you the shape of the gap.
Does it work with S3 / R2 / remote storage?
Yes. It goes through XenForo's own abstracted filesystem, so whatever adapter your forum uses works. Always pass --index on remote storage — without it, every row is a separate network round-trip.
Do I need to install an add-on?
No. It is a single standalone PHP file placed in your forum root, run from the command line. Delete it when you are finished if you prefer.
Why does it need file_key rather than file_hash?
Because that is what XenForo actually uses to build the stored path. They are both 32-character hex strings and are easy to mix up. The script aborts on schemas without the column rather than deriving wrong paths.