# Recover missing or damaged media

Source: https://frameleaf.app/docs/admin/media-recovery/

When Frameleaf can no longer read an original, [Library Care](https://frameleaf.app/docs/using/library-care/) finds it again or puts back a verified, byte-for-byte copy, and the photo keeps its albums, people and links. This page is the administrator's side: what to check first, how recovery picks a safe copy, and what each count and report means.

Most of the time you won't need these tools. When a file is found missing or damaged, Frameleaf first tries to fix it by itself: it repairs damaged photos, searches for an exact copy, restores the original from Cloud Backup, asks iCloud Photos for a photo that came from there, and asks the owner's phones. A good copy that arrives any other way is used too: an upload from the web, a phone or the desktop app, a Google Photos or Eagle import, a browser capture or a restored preservation copy goes back in the lost or damaged file's place instead of being turned away as a duplicate. Each file's owner sees what it did in [Damaged and missing files](https://frameleaf.app/docs/using/damaged-and-missing-files/), where any fix can be undone.

The tools are in **Library Care**, under **Tools**: **Missing files** and **Damaged files**. They're administrator tools; you can review your own findings, one other account or all accounts. Another person's [Locked](https://frameleaf.app/docs/using/private-content/) items are never listed, counted or changed.

## Start with storage access

A missing-file report means Frameleaf can't reach the file it expects. Usually the file is still there: a moved or offline drive, a changed mount path and wrong permissions all look the same.

If many files go missing at once, check your mounts and permissions first. Restoring access is often all you need, and every finding clears on the next scan.

Keep your backups and recovery copies until you've opened the recovered media and checked it.

## Find a file that moved or was renamed

1. In **Library Care**, open **Missing files** and choose **Scan again**.
2. Choose **Locate originals** and, in **Choose candidate originals**, pick where to look: library storage, external libraries and any recovery locations.
3. Review each candidate. It shows whether it's an exact match and whether it opens correctly.
4. Choose **Relink verified matches**, then open the item to check it.

Locate matches on the **content checksum** Frameleaf saved for the original, not on names or folders. So if a storage move renamed `IMG_1234.JPG` and put it in dated folders, Locate still recognises it, because the bytes are identical. Anything less certain, such as a matching name or a similar thumbnail, stays for you to review.

Locate searches the configured locations, with limits on how much it scans. If it finds nothing, the file is outside those locations, or the item has no saved content checksum to match against. Items from [external libraries](https://frameleaf.app/docs/admin/external-libraries/) that were checksummed from their path, not their contents, can't be matched this way.

### Recovery locations

Recovery locations are extra folders Library Care searches for copies, such as a backup drive. Set them with `FRAMELEAF_RECOVERY_ROOTS` in `.env`, as `Label=path` entries separated by `;` (the label is optional):

```bash
FRAMELEAF_RECOVERY_ROOTS="Verified backup=/mnt/backup/photos;/mnt/photos/recovered"
```

Each path must be an absolute path inside the server container. The filesystem root and repeated paths are refused, and the server won't start until you fix them, so a typo is caught straight away. Mount these folders into the server container read-only. Frameleaf only ever reads them: a copy found there is copied into your library storage.

## Recover a matching copy from iCloud

If the same original is still in iCloud, [iCloud Photos sync](https://frameleaf.app/docs/migrate/icloud-photos/) brings back a verified copy.

For a photo that came from iCloud Photos, Library care asks by itself. When copies and Cloud Backup have nothing, it puts the photo first in line for iCloud. A connection that syncs automatically starts a sync straight away; one set to sync only when asked waits for its next sync. The photo's history says **Asked iCloud Photos**, then **iCloud Photos had the original** or **Not in iCloud**.

For a photo that never came from iCloud but is in the person's iCloud library:

1. Turn on iCloud sync for the server, then have the person connect their Apple account.
2. Select a library or album that contains the original, save the settings and choose **Run now**.
3. The server downloads what it needs, computes content checksums and validates the media file itself.
4. When the copy checks out, the existing item is repaired in place. It keeps its ID, albums, people and other links, and the matching findings are marked resolved without another full scan.
5. Check the progress, then open the photo from **Results** on the iCloud Photos page.

The downloaded file must match the saved content exactly, so you get back your original, not a lookalike. A re-encoded, resized or edited version has different bytes and isn't used to replace it. A valid Apple-edited version can be kept as a separate member of a stack instead.

If only the movie part of a Live Photo is damaged, it can be recovered on its own. Each original, edit and movie is repaired separately.

### Managed and external libraries

Managed items are stored by Frameleaf. [External library](https://frameleaf.app/docs/admin/external-libraries/) items point at files you manage yourself.

Recovery for external libraries is off by default. When you allow it, a verified matching copy is stored under Frameleaf's management and the item keeps its identity; the original external path is never overwritten. When it's off, a damaged external match stays as a review item and the downloaded recovery copy is kept.

Importing hidden Apple media, and recovering into Locked items, need the matching privacy permission. The hidden movie part of an ordinary Live Photo is a normal part of that photo, not a Locked item.

## Understand the results

| Result | What it means and what to do |
| --- | --- |
| Missing or unreadable | Check storage and permissions, then locate or recover a matching copy |
| Confirmed corruption | The file failed media validation or differs from its saved checksum. Recover a matching good original if there is one |
| Unsupported RAW or format | The server can't decode it to check it. The file isn't known to be damaged |
| Validation timeout | The check didn't finish. Give that file a longer timeout if it needs one |
| Requires review | Identity, privacy, external library recovery or another safety rule stopped automatic completion. Read the reason |
| Resolved | The finding is resolved. Open the item and check it |

**Trash confirmed damage** moves recently re-checked damaged items to the trash after a PIN and typed confirmation. Use it once you've given up on recovering them: iCloud sync doesn't restore items you trashed on purpose.

## The last good copy is kept

When [identical files](https://frameleaf.app/docs/admin/physical-deduplication/) are merged, the extra copies wait in **Unused files**. If the file the photos share later goes missing or is damaged, a copy in Unused files may be the only good one left. So while any photo with the same contents has an open missing or damaged finding, **Empty Unused files** leaves that copy where it is and says it's still waiting. Once the finding is settled, it can be deleted as before.

## Why the counts differ

Different screens count different things, so compare the same scope and filters before you conclude anything is lost.

| Screen or count | What it includes |
| --- | --- |
| Photo and video statistics | Visible items. Server totals leave out the hidden movie parts of Live Photos, and per-person totals also apply visibility and privacy filters |
| Media health scan | Every item in the scan, including the hidden movie parts of Live Photos |
| iCloud photos and videos | Photos and videos found in the selected iCloud scope |
| iCloud file resources | Individual originals, edits, RAW alternatives and Live Photo parts |
| Orphaned files | Files on disk the reporting tool can't link to anything it checks, including generated files and sidecars |

For example, one visible Live Photo can count as one photo and two file resources, and its hidden movie is checked by the media health scan even though the photo statistics leave it out.

## Orphaned transcodes and XMP files

Treat an orphan report as a list to investigate, not a deletion list. A transcode has different bytes from the original video, and an XMP sidecar is a separate metadata file, so neither matches the original's checksum. The iCloud connector leaves orphans alone and doesn't reconnect transcodes or sidecars.

Before removing anything, compare the reported paths with the database, your storage configuration and any files shared between items. The [integrity checks](https://frameleaf.app/docs/admin/system-integrity/) and [useful database queries](https://frameleaf.app/docs/admin/database/#diagnose-connection-failures) can help.
