Common Warnings

While using this application, warnings might appear. This is either due to the fact that the API is not completely understood and/or inconsistent. The overall goals of the application can still be achieved, however a small percentage of assets might be miss-represented. The impact can be gauged by observing the below messages.

For most warnings, the CLI only prints a count summary, the details are written to the log file. Each warning is logged with the level WARN and the source RuntimeWarning, for example:

[2026-01-01T00:00:00.000Z] WARN RuntimeWarning: Extraneous file found in directory /opt/icloud-photos-library/My Album

The same warnings are also exported as warn-* fields of the metrics file and as type label of the icps_warnings_total Prometheus metric.

The suppress warnings flag only hides the warnings printed directly to the CLI (unknown filetype, indexing, schedule frequency, MFA, trusted phone numbers, web server and resource file warnings). The count summaries printed after each sync step, as well as the log file, are not affected.

Syncing

Warning: Detected unknown filetype (descriptor with ext)

Supported filetypes need to be hardcoded in the application. This error indicates that one of your iCloud assets has a filetype that is currently not supported. If you have error reporting enabled, your filetype is reported to the author automatically and the message is printed without the Warning: prefix (...: This error will be automatically reported (See GH issue 143 for more information)). Otherwise, report your filetype in the open issue.

The assets with unknown filetype will be ignored during syncing, the remaining files will sync as expected. Those assets are also counted towards the unable to load remote assets warning.

Search the log file for a RuntimeWarning of the format Unknown file extension ${ext} for descriptor ${descriptor}.

Warning: Detected number extraneous files

There should only be symlinks in folders and non-archived albums. Extraneous files are highlighted during library loading.

Search the log file for a RuntimeWarning of the format Extraneous file found in directory ${filePath}, to find and remove the extraneous file from your file system.

Warning: Unable to load number local assets

There are various reasons, why the application cannot load an asset from the user's local library (e.g. permission issues, or a file with an unknown or missing extension in _All-Photos/_Shared-Photos). The assets that could not be loaded will be ignored during the synchronization. Local files with an unknown extension are not reported as unknown filetype.

Search the log file for a RuntimeWarning of the format Error while loading file ${filePath}: ${errDescription} to get an idea, why loading fails.

Warning: Detected number albums, where asset counts don't match

In an initial set, the API is queried for the number of assets in a given album. This is followed by a query to get all assets associated with the album. For some reason those APIs sometimes return contradicting results (I suspect an error within the iCloud backend).

Search the log file for a RuntimeWarning of the format Expected ${expectedCount} CPLAssets & CPLMasters, but got ${actualCPLAssetCount} CPLAssets and ${actualCPLMasterCount} CPLMasters for album ${albumId} to understand which albums and assets are impacted. albumId is the album's UUID (the name of its hidden .{UUID} folder in the library), or All photos for the whole library.

Records that could not be parsed are listed with a WARN log line of the format ${number} unexpected errors for ${albumId}: ${errorCodes}. Those records are ignored.

Warning: Unable to load number remote assets

There are various reasons, why the application cannot load an asset from the iCloud Photos Library backend (e.g. unreliable network connection). The assets that could not be loaded will be ignored during the synchronization.

Search the log file for a RuntimeWarning of the format Error while loading iCloud asset ${recordName}: ${errDescription} to understand which assets are impacted.

Warning: Detected number errors while adding assets

A failed download (network or HTTP error) or a failed verification of the downloaded file only affects this asset. The sync continues with the remaining assets and the affected assets will be retried during the next sync.

File system errors (e.g. missing permissions or no space left on the device) affect all assets: They abort the current sync attempt, which is then retried.

Search the log file for a RuntimeWarning of the format Error while verifying asset ${assetName}: ${errDescription} to understand which assets are impacted. assetName is the asset's file checksum, which (URL-safe encoded) is also the base of its file name within _All-Photos.

Warning: Detected number errors while linking assets to albums

When linking assets into the directory tree various errors can happen (e.g. assets with a naming conflict in the same folder). This leads to assets missing within the album structure, while still being within the _All-Photos folder.

Search the log file for a RuntimeWarning of the format Error while linking ${srcPath} to ${dstPath}: ${errDescription} to understand which assets and albums are impacted.

Warning: Detected number errors while writing albums

There are various reasons, why the application cannot write an an album to disk (e.g. permission issues). The albums experiencing this error are most likely not written to disk or missing assets.

Search the log file for a RuntimeWarning of the format Error while writing album ${albumName}: ${errDescription} to understand which albums are impacted.

Indexing in progress

Printed as Warning: ICLOUD_PHOTOS_INDEXING_IN_PROGRESS: iCloud reports indexing in progress, continuing sync without deleting local assets (zone: ${zone}, progress ${progress}), if iCloud reports that the library (PrimarySync) or the shared library (SharedSync-*) is still being indexed.

The sync continues, but local assets are not deleted. While iCloud is indexing, assets that are not indexed yet might be missing from the remote state. Deleting every local asset that is missing remotely could therefore remove assets that still exist in iCloud. Instead, those assets are kept, and the log contains iCloud reports indexing in progress, deferring deletion of ${number} local assets until indexing has finished. They are deleted by the first sync after iCloud reports indexing as finished. New and changed assets, as well as albums, are synced as usual.

Since October 2026, iCloud reports indexing jobs as running with a progress of 0, even though all assets are available, and the reported state changes between requests. Deletions are therefore only delayed until a sync sees the finished state. Earlier versions of this application refused to sync in that case (Indexing in progress, try again later).

Search the log file for a RuntimeWarning of the format ICLOUD_PHOTOS_INDEXING_IN_PROGRESS: ....

Detected error during sync

Detected error during sync: ${errDescription}
Refreshing iCloud connection & retrying (attempt #${number})...

The current sync attempt failed (e.g. due to a network error, an expired session or a file system error). The application re-establishes the iCloud connection and starts over, keeping all assets that were already written. Each retry counts towards the maximum number of retries, after which the sync fails.

The same message is logged as RuntimeWarning.

Download URLs expired after writing number assets, refreshing remote state...

The download URLs, which are part of the fetched metadata, expire after roughly 15 minutes. Large libraries therefore need multiple passes: The remote state is fetched again and the sync continues with the remaining assets. As long as assets were written since the previous refresh, this does not count as a retry.

CloudKit asked to retry request after numbers (retry n/10)

The iCloud backend is throttling the application. All metadata requests are paused for the requested time. If the same request is throttled more than 10 times, it fails and the sync is retried. If this happens regularly, consider lowering the metadata rate.

This message is only written to the log file.

Sync execution skipped, because a job is still running

In daemon mode, the scheduled sync was skipped, because the previous sync (or a re-authentication requested through the Web UI) was still running. The message includes the time of the next scheduled run. If this happens regularly, choose a less frequent schedule.

Schedule frequency

Printed as Warning: APP_SCHEDULE_FREQUENCY: Schedule triggers syncs more often than once per hour, frequent sign-ins might be throttled by Apple (...) when the daemon starts, if the configured schedule triggers syncs less than one hour apart. Every scheduled sync signs in to iCloud, and frequent sign-ins can be throttled by Apple.

This is most likely a mistake in the cron schedule: the first field of a cron schedule is the minute, so * 2 * * * runs every minute between 02:00 and 02:59, instead of once at 02:00. In this case, the message suggests the schedule that was most likely meant, e.g. '* 2 * * *' runs every minute between 02:00 and 02:59 - did you mean '0 2 * * *'?. For all other schedules, it includes the shortest interval between two runs, e.g. '*/15 * * * *' runs as often as every 15 minutes. Use crontab.guru to check a schedule.

The schedule is still applied. If the frequent syncs are intended, the warning can be ignored. It is also logged as a RuntimeWarning.

Authentication & Web UI

MFA error

Printed as Warning: MFA_RESEND_FAILED: Unable to resend MFA code caused by ${errDescription}, if the MFA code could not be requested through the selected method. Request it again, or choose a different method.

Search the log file for a RuntimeWarning of the format Error within MFA flow: ${errDescription}.

Trusted phone numbers error

Printed as Warning: MFA_NO_PHONE_NUMBERS: Unable to acquire trusted phone numbers caused by ${errDescription}, if the trusted phone numbers of the account could not be loaded. The Web UI can then not offer the phone numbers for requesting the MFA code via SMS or voice call, the code pushed to the trusted devices is not affected.

Search the log file for a RuntimeWarning of the format Error while loading trusted phone numbers: ${errDescription}.

Web server error

Printed, if the Web UI or its API received a request it could not process, e.g. an unknown endpoint, an invalid MFA code format, an MFA code while none was expected, or a request while a sync is in progress. The request is rejected, the application continues.

Search the log file for a RuntimeWarning of the format Error within web server: ${errDescription}.

Resource file error

Printed, if the resource file .icloud-photos-sync in the data directory could not be read or written (e.g. due to missing permissions). If it cannot be written, the trust token is not persisted and a new MFA code is required upon the next start.

Search the log file for a RuntimeWarning of the format Error while accessing resource file: ${errDescription}.

Archiving

Detected number errors while archiving assets

There are various reasons, why the application cannot archive an asset (e.g. permission issues). The asset experiencing this error might not be correctly archived or corrupted. The remote asset will not be deleted in this case.

Search the log file for a RuntimeWarning of the format Error while archiving asset ${assetPath}: ${errDescription} to understand which assets are impacted.