Recover missing or damaged media

When Frameleaf can no longer read an original, Library Care helps you find it again or put back a verified copy. This page is the administrator’s side: what to check first, how recovery decides a copy is safe, and how to read the different counts and reports.

The tools are in Library Care: Review missing media and Review damaged media. The Missing originals and Damaged media queues are administrator tools; you can review your own findings, one other account or all accounts. Another person’s Locked items are never listed, counted or changed.

Start with storage access

A missing-file report means Frameleaf can’t reach the file it expects. It doesn’t prove anyone deleted it. A moved or offline drive, a changed mount path, or wrong permissions all look the same.

If many files go missing at once, check your mounts and permissions before anything else. Restoring access to the existing files is often all that’s needed. Creating duplicates or deleting findings doesn’t fix storage that isn’t available.

Keep existing 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 media and run a scan.
2. Choose Locate originals and 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.

A candidate is accepted only when its content checksum matches what Frameleaf saved for the original. File names and folders aren’t identity: a storage move can rename IMG_1234.JPG and put it in dated folders while the bytes stay identical, and Locate still recognises it. Matching names, similar thumbnails or equal video lengths are never enough. Uncertain candidates stay for review.

Locate searches only the configured locations, with limits on how much it scans; it doesn’t search every disk or any path on the server. If it finds nothing, the file may be outside those locations, or the item may have no trustworthy saved content checksum. Items from 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 may search 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):

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 can’t quietly search somewhere unexpected. Mount these folders into the server container read-only. Recovery locations are only ever read; a copy found there is copied into your library storage first.

Recover a matching copy from iCloud

If the same original is still in iCloud, iCloud Photos sync can provide a verified recovery copy.

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 checks the actual media. A matching checksum in the database doesn’t make a damaged file healthy, so the file itself is validated too.
4. If recovery is safe, 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 use Recent verified results, then View media to open it.

The downloaded file must match the saved content exactly. A re-encoded, resized or edited version has different bytes and can’t automatically replace a missing original, even if it shows the same scene. 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. Repairing one part doesn’t mean every related original, edit or movie is repaired.

Managed and external libraries

Managed items are stored by Frameleaf. External library items point at files you manage yourself.

Recovery for external libraries is off by default. When it’s allowed, a verified matching copy can be stored under Frameleaf’s management while the item keeps its identity; the original external path is never overwritten. When it isn’t allowed, 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 isn’t the same as 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. This isn’t confirmed damage
Validation timeout	The check didn’t finish. Consider whether that file needs a longer timeout
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. That isn’t recovery. iCloud sync doesn’t restore items that were trashed on purpose, so check what’s in the library before you try a recovery again.

Why the counts differ

Different screens count different things. Compare the same scope and filters before deciding photos are 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

An orphan report isn’t a deletion list. A transcode has different bytes from the original video, and an XMP sidecar is a separate metadata file, so neither can be matched by the original’s checksum. Regenerating metadata doesn’t by itself prove that every reported orphan can be thrown away, and the iCloud connector doesn’t delete orphans or reconnect transcodes and sidecars.

Before removing anything, compare the reported paths with the database, your storage configuration and any files shared between items. A large orphan count calls for that investigation, not a blanket clean-up. The integrity checks and useful database queries can help.