Sync Results and Troubleshooting

Use the Sync run's result to identify affected work, then inspect the per-file messages to find its cause. A Partial Failure can contain different causes for different files. The run status alone does not establish which operation needs correcting.

Run and File Records

Files.com records a complete log of every sync action and each sync run, including details about which folders were listed, which files were transferred, and which files were skipped.

File History records each file the Sync reads as a download at the source path and each file it writes as an upload by the Sync's user. Transfers through a Child Site or Connected Site folder under _/Sites/<site-id> are recorded on both sites, using each site's own paths. The Sync's action and run logs remain on the site where it is configured.

You can download the raw logs for processing on your side. Logs are text files where each line of the file is a JSON hash containing the information about a particular log item. Process the log file line by line, running each line through a JSON parser.

We also provide a rich API for querying these logs. This API offers many filtering options.

SIEM integrations and Log File Streaming can export integration logs for external monitoring or retention. For selected Sync run outcomes, use Event Channels.

When errors are detected in a sync, Files.com automatically alerts Site Administrators via email. You can also use the Sync Logs API to query for failed external events.

To see all Sync Logs across your site, go to the Automation and Flow page under Logging in the left navigation in the Web UI.

Files.com retries failures automatically. If a Sync fails, it is logged as an error once all retry attempts have been exhausted. Each scheduled Sync is independent, so one scheduled Sync failing does not prevent the next scheduled Sync from attempting to run.

Sync Run Outcomes

A run that ends in Partial Failure transferred some of its files and failed on others. Files in the same run can fail for different reasons, so inspect the per-file errors before deciding what to fix. Files.com records a message against every file that failed, and those per-file messages are what identify the cause.

Most sync failures are explained on the page for the behavior that produced them. A file skipped for changing mid-run is covered under files changing during a run, folders omitted for colliding on case under case sensitivity, and files a remote server refuses outright under file size limitations. The failures below need diagnosis across more than one of those causes.

Site Alert Emails

When a sync operation fails, Site Administrators who have the Sync failures alert email preference enabled receive an email notification. If no Site Administrator has that preference enabled, all administrators receive the alert.

If there are multiple failed syncs, all of them appear in the same email. The email includes a link to the details of each failed sync in the Sync Log along with the time of the failure.

To receive alerts for sync successes or to route sync outcomes to webhooks, Slack, Teams, Amazon SNS, or Google Cloud Pub/Sub, configure an Event Channel subscription for sync_run.success.v1, sync_run.failure.v1, or other sync run event types.

Connection Is Lost or Is Unresponsive

The error Connection is lost or is unresponsive, please try again. means something on the remote server took too long to respond. It appears on the failed operation of a run that ends in Failure or Partial Failure, often a List operation, and begins with the ID, type, and name of the Remote Server used by the sync.

A target folder too large to list produces this error. Every sync compares the source files with the destination files, including the metadata you would see in a folder listing, so a wide and deep folder structure takes a long time to list recursively. A listing that takes more than a few minutes is problematic. Point the sync at a smaller target folder, split the work across multiple syncs each covering a smaller subfolder, or reduce the number of items in the folder.

It also appears when a single file takes longer to transfer than the remote server's connection timeout allows. An indicator of this is one file failing on every run while the rest of the sync succeeds. Ask the administrator of the remote server to allow a longer connection duration, or reduce the file sizes so each file fits inside the duration the server allows.

Local File or Folder Not Found

The error Local file/folder not found: followed by the name of the item means the item disappeared after the run started but before the run reached it. Something deleted, moved, or renamed it in between.

A sync builds its list of names first and then works through that list, so an item renamed partway through a run cannot be found under the name that was recorded. The next run picks the file up under its new name, as long as nothing renames, moves, or deletes it again.

A handful of these errors on a run that otherwise succeeds is the normal result of a busy source folder. When they arrive in bulk, or the affected files change from run to run, another process is competing for the same location. A run may also report that the destination already exists, which happens when another job writes the same destination path first and Files.com declines to overwrite what is already there. Other times a run skips files with no warning at all.

Concurrent Access covers which overlaps cause this and how to separate two jobs that have to use the same location.

Failures That Repeat on the Same Files

When the same files fail on every run and the logs record the same message each time, the cause is a fixed obstacle rather than a passing one. Check the file sizes the remote server accepts, the filename requirements on both sides, the permissions the sync account holds, and the credentials and IP allowlisting the remote server requires. When only one file fails this way, it may instead be hitting the connection timeout.

Identify the failed operation and path in the Sync log and the Outbound Connections log. A failed listing, download, upload, replacement, or source deletion needs different permissions. Ask the remote administrator to check that operation for the connection’s actual account, rather than granting full access to both sides.

If a test is needed, use a separate Sync with External Trigger, a small completed sample, an isolated destination, and After Copying set to keep. Verify the actual host, credentials, and paths; run Dry run before a manual transfer. An isolated destination can still replace its existing files, so use a new sample name and keep it outside application pickup paths. Test replacement or deletion separately on disposable samples only when that is the failed operation.

A successful test establishes only the operations and paths it exercised. Success in another folder does not prove access to the original folder. Compare the remote account’s rights on the failed path, make the required correction, and verify that operation with an agreed sample before restoring the production schedule.