# System integrity

Source: https://frameleaf.app/docs/admin/system-integrity/

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

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](https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/using/photos-found-on-the-drive/).

### Schedule

All three run in the **Check files** step of the [overnight schedule](https://frameleaf.app/docs/admin/jobs/#nightly-tasks), 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](https://frameleaf.app/docs/admin/jobs/), one at a time.

### 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](https://frameleaf.app/docs/using/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

**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](https://frameleaf.app/docs/using/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.

:::tip
In **Background work**, open the menu on the **Ready to browse** row and choose **Catch up on what’s missing**, so every item has its thumbnails and encoded videos. The server logs show any items that have problems while they run.
:::

**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](https://frameleaf.app/docs/admin/media-recovery/).

**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.

:::caution
Deleting a spare copy in **Photos found on the drive**, or running **Delete untracked files from disk**, removes files from the drive for good. They don't go to Trash.
:::

## 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](https://frameleaf.app/docs/api/overview/).

## 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 `.frameleaf`, the first time
2. reads the marker file
3. 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

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

```text
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

:::danger
The folder checks protect your library from a missing mount or wrong permissions, and an error almost always means something needs fixing. Turn them off only when you know exactly why they fail.
:::

To ignore folder check errors, set this in your `.env` file and recreate the containers:

```bash
FRAMELEAF_IGNORE_MOUNT_CHECK_ERRORS=true
```
