System integrity

Frameleaf checks your storage in two ways: integrity checks that run on a schedule and look for missing, unknown and changed files, and folder checks every time the server starts, to make sure it can read and write its storage.

Integrity checks

There are three checks. They only read the library and never change files.

Check	What it finds
Untracked files	Files in Frameleaf’s folders that the database has no record of
Missing files	Files the database knows about that aren’t on disk
Checksum mismatch	Files whose contents no longer match the checksum Frameleaf stored

Schedule

All three run every night at 3:00 AM by default. Change the schedule, or turn a check off, in Administration, then Settings, then Integrity checks.

The checksum check reads every byte of every file, so it’s the heaviest. It has two extra limits, so it can work through a large library over a few nights instead of all at once:

Setting	What it does	Default
Time limit	The longest the checksum check runs each time, in milliseconds	3,600,000 (1 hour)
Percentage limit	The most of the library it checks each time, from 0.01 to 1	1 (all of it)

The checks run in the Integrity checks queue, one at a time.

Review the reports

See the results in Administration, then Maintenance, under Integrity checks. Each check shows when it last ran and how many findings it has.

• Run check runs one check in full now. Run all checks runs all three.
• View report lists the findings. Filter them by path, or download the report file.
• Recheck findings looks only at the items already reported and clears those that are fixed. It’s much quicker than a full check.
• You can delete a single finding or a whole report. For untracked files, this deletes the file from disk and can’t be undone. For missing files and checksum mismatches, the item is moved to the trash, or its generated file is removed.

The same checks are available as maintenance jobs in Settings, then Compute & jobs, then Create job: Find missing files, Find untracked files and Verify checksums, each with a recheck and a “clear reports” option. Clearing reports deletes only the reports, never your files.

What usually causes each finding

Untracked files are the most common. Often they’re thumbnails or encoded videos that were only partly created at some point and never cleaned up. Those are usually safe to delete, because both can be generated again. Anything else needs looking at case by case: check whether the photo is already in Frameleaf, and think about how the file could have got there.

Tip

Run the missing jobs for Thumbnails and Playback videos in Compute & jobs to make sure every item has its thumbnails and encoded videos. Watch the server logs while they run, in case some items have problems.

Missing files are files the database expects but can’t find. Someone may have deleted a file from the library folder on disk (Frameleaf doesn’t support that), or there may be a problem with your storage, such as a drive that isn’t mounted. Investigate carefully before acting. To look for a file that has moved, see Recover missing or damaged media.

Checksum mismatches often point to file system corruption. They also appear if someone edited a file in the library folder directly, which isn’t supported. Look at each item, and think about whether it or its metadata was changed. If a file was edited on purpose, the supported fix is to delete it from Frameleaf and upload it again as a new item.

Caution

An untracked file report isn’t a list of files to delete. Make sure a file really is unneeded before you remove it.

Folder checks at start-up

Every time the server starts, it checks that it can read and write each of its storage folders: upload/, library/, thumbs/, encoded-video/, profile/ and backups/. For each folder it:

1. creates a hidden marker file named .immich, the first time
2. reads the marker file
3. overwrites the marker file

If any step fails, the server doesn’t start. This catches two common problems:

• Wrong permissions: the server can’t read or write the folder.
• A missing mount: the marker file should be there but isn’t, which usually means a volume isn’t mounted where it was before.

The .immich files are markers that help Frameleaf recognise its folders. Don’t create or delete them yourself, except in the cases below.

Missing marker files

An error like this means the server wrote marker files before, but can’t find one now:

Verifying system mount folder checks (enabled=true)
...
ENOENT: no such file or directory, open 'upload/encoded-video/.immich'

Possible causes:

• Permissions: the file exists, but the server can’t read it.
• The mount changed: correct the volume in your Compose file.
• Someone deleted the file: create it again with touch .immich in that folder.
• A partial restore: you restored from a backup but not every folder. Restore all the folders, or create .immich in each missing one.

Turn the checks off

Danger

The folder checks catch real problems that people have run into, and an error usually means something needs fixing. Only turn them off if you’re sure you know why they fail.

To ignore folder check errors, set this in your .env file and restart:

FRAMELEAF_IGNORE_MOUNT_CHECK_ERRORS=true