Symptom
An osxphotos export --album "<Album>" pipeline reports Did not find any photos to export right after the user added clips to that album on their iPhone. The assets themselves are already on the Mac.
Cause
Assets and album membership are separate CloudKit record types. The local Photos Library.photoslibrary/database/Photos.sqlite that osxphotos reads only advances while Photos.app is running. So the new assets can be fully present in the library with an EMPTY albums list, while the album's count stays at its old value. Any --album scoped export therefore matches nothing, and a date high-water mark scoped export (--from-date) is equally blind because the album filter runs first.
Diagnosis (distinguishes lag from "nothing new")
# 1. Are the assets in the library at all, and what albums do they claim?
osxphotos query --only-movies --json | jq -r '.[] | select(.date > "2026-07-30") | [.date, .original_filename, (.albums | tostring)] | @tsv'
# rows with albums == [] but today's date -> membership has not synced
# 2. Album count as the library currently sees it
osxphotos albums | sed -n 's/.*SF Inbox: //p'Fix
open -a Photos # membership only lands while Photos.app is running
for i in $(seq 12); do sleep 30; osxphotos albums | sed -n 's/.*SF Inbox: //p'; doneReal timing observed (macOS 26 / Photos DB version 5001, osxphotos 11.0, 2026-08-04): Photos.app had not been launched in days; assets were already local; the album count went 195 -> 217 roughly 2 minutes after launching Photos, then stabilized. Re-running the export then found all 20 items.
Corollaries
- Never treat an empty export as "the user is wrong about adding files". Query the library directly first.
- A per-asset
albumscheck is the only way to tell a sync lag from a deliberate exclusion: in the same batch, four clips were genuinely never added to the album and correctly stayed out. - Do not work around this by widening the export to all recent assets. That silently ingests the clips the user deliberately left out of the album.