System integrity
Restore Frameleaf from a backup, and use maintenance mode Watch on YouTube
Frameleaf keeps an eye on your library for you, so you hear about a missing or damaged file long before you need it. It checks your storage in two ways: integrity checks run on a schedule and look for missing files, damaged files and files that aren’t in a library, and folder checks run every time the server starts to make sure it can read and write its storage.
Integrity checks
Section titled “Integrity checks”There are three checks. None of them moves, renames or deletes a file.
| Check | What it finds |
|---|---|
| Missing files | Files in your library that are no longer on the drive. The photos still show their previews |
| Damaged files | Files whose contents have changed since Frameleaf stored them, so they may not open |
| Files not in a library | Files in Frameleaf’s folders on the drive that are in nobody’s library, usually left by an upload that was cut off |
When a check finds a missing or damaged file, Frameleaf tries to fix it by itself straight away, keeps any damaged file, and lists what it did in Damaged and missing files. Whether damaged photos are repaired by themselves is set in File checks, under When a check finds a problem.
When a check finds a photo or video that isn’t in a library, Frameleaf reads it once and sorts it by itself: a photo that went missing is put back, a photo no library has is added, and a second copy of a photo you already have is left on the drive. You see each one as a picture, and can undo it, in Photos found on the drive.
Schedule
Section titled “Schedule”All three run in the Check files step of the overnight schedule, the last step of the night, after any added folders and iCloud Photos are checked. The night starts at midnight by default; change it, or run the step once a week instead, in Overnight schedule. Turn a check off with its Look for … switch in Settings, then Library care, then File checks, under What is checked. Overnight schedule, under When checks run, opens the nightly settings in Computers & background work.
The damage check reads every byte of every file, so it’s the heaviest. It has two extra limits, under Advanced: how much is checked each night, so it can work through a large library over a few nights instead of all at once:
| Setting | What it does | Default |
|---|---|---|
| Stop after | The longest the damage check runs each night. The next night carries on where it left off | 1 hour |
| How much of the library is checked each night | The whole library, Half or A quarter | The whole library |
The checks run as the Checking for damaged files task in Background work, one at a time.
Review the reports
Section titled “Review the reports”See the results in Settings, then Library care, then File checks. The status at the top says Every file is present and undamaged, Not checked yet, or how many files need attention. Each check under What is checked shows when it last ran.
- Check now next to a check runs that check now. Check now at the top runs every check that is on, and once something was found it reads Check again. Recent checks shows what each run looked at and how long it took.
- Each kind that found something gets its own list, showing the first few findings. Details for support lists every finding with the place of its file on the drive: See every path, or download the list as a spreadsheet. The spreadsheet also gives each row the photo’s original file name, including rows for its thumbnails and other files Frameleaf made from it, so you can tell which photo a Missing files or Damaged files row is about. Files that aren’t in a library have no name there.
- Remove from list takes one finding off the list, and Clear this list forgets them all. Neither touches a file; anything still wrong is listed again at the next check.
- For Missing files and Damaged files, Move these photos to Trash… (the button counts them) moves the items to the trash, and asks first.
- For Files not in a library, the list says what became of the files: how many are photos again, how many are spare copies and how many need a decision from you, with a few of the photos. See the photos opens Photos found on the drive. File checks doesn’t offer to delete these files.
The same checks are available as maintenance jobs. Open Settings, then Computers & background work, then Background work, choose Advanced, then Create a job at the foot of the page: Find missing files, Find untracked files and Verify checksums, each with a recheck. Each also has a job that acts on every finding at once, and these change your files: Move photos with missing files to Trash, Move photos with checksum mismatches to Trash, and Delete untracked files from disk, which can’t be undone. On the Everyday view, Check files for damage in the Upkeep row’s menu starts the checksum check.
What usually causes each finding
Section titled “What usually causes each finding”Files not in a library are the most common. Usually an upload was cut off, or a file was renamed or moved outside Frameleaf. You don’t have to work out which: Frameleaf compares each file’s contents with the photos in every library and sorts it by itself. Anything it won’t decide waits under Needs you in Photos found on the drive, such as a file in a folder no account uses, or a file named like a photo that won’t open.
Previews and encoded videos left behind by photos that are gone are cleared without asking, because Frameleaf can make them again. They aren’t listed.
Missing files are files the database expects but can’t find. Usually a file was deleted from the library folder on disk (Frameleaf doesn’t support that), or a drive isn’t mounted. Find the cause before you act on them. To track down a file that has moved, see Recover missing or damaged media.
Damaged files often point to file system corruption. They also appear when a file in the library folder was edited directly, which Frameleaf doesn’t support. Look at each item to see whether it or its metadata changed. If a file was edited on purpose, delete it from Frameleaf and upload it again as a new item.
The check after an upgrade
Section titled “The check after an upgrade”After every upgrade, the server compares the library with how it was just before. Before the new version makes its changes, it notes how many photos and videos each person and each added folder has, when the newest one was added, and which of its folders hold files. Once the new version has started, it counts again.
The check asks for attention when:
- a drive or folder that was there before the upgrade isn’t mounted, or a different drive is in its place
- noticeably fewer photos and videos are in the library than before (more than 1 in 200)
- the newest photo is older than it was before
- a folder that held files now holds none
Anything else counts as fine. A drive that isn’t mounted is named first, as a drive, not as thousands of missing photos. The check never stops the server starting, and it changes nothing.
To recognise its drives, the server keeps a small file named .frameleaf-sentinel in each of its own folders and in each added folder, written the first time the folder is in place and has files. Leave these files where they are. An empty mount point never gets one, and a read-only share is recognised by its files instead.
The result isn’t shown on a Settings page. Administrators can read the latest comparison from the API, at GET /api/admin/upgrade-check; see API overview.
Folder checks at start-up
Section titled “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:
- creates a hidden marker file named
.frameleaf, the first time - reads the marker file
- overwrites the marker file
An older or imported library may have markers named .immich. The server checks each one is there and renames it to .frameleaf the first time it starts.
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 .frameleaf files help Frameleaf recognise its folders. Leave them in place, apart from the cases below.
Missing marker files
Section titled “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/.frameleaf'The cause is usually one of these:
- Permissions: the file exists, but the server can’t read it. Fix the folder’s permissions.
- The mount changed: correct the volume in your Compose file.
- The marker was deleted: check that this is the original mounted folder and that its media is intact, then recover the marker from a matching backup or follow the recovery instructions for your release.
- A partial restore: restore the missing folders from the matching backup. An empty marker file would only hide the real problem, so fix the mount or restore instead.
Turn the checks off
Section titled “Turn the checks off”To ignore folder check errors, set this in your .env file and recreate the containers:
FRAMELEAF_IGNORE_MOUNT_CHECK_ERRORS=true© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.
