Get Nextcloud Desktop Sync Moving Past “Processing Files”

If the Nextcloud Desktop Client stays on “Processing files,” open the account’s sync activity and identify whether one file repeatedly shows an error or the client is still scanning a large folder tree. Check that item first, then review ignored-file rules and the server connection. Restarting may clear a temporary stall, but deleting the sync database or recreating the sync connection should be a later step because it can reset selective-sync choices or trigger a large recheck.

Find out what is actually stuck

Open the Nextcloud menu from the system tray on Windows or Linux, or the menu bar on macOS, and open the account status. Look for a repeating filename, a visible error, or a queue that changes. The client distinguishes synchronizing, paused, offline, warning, and error states; a blue activity icon does not by itself prove that data is uploading. In classic sync mode, file-manager overlays can help: blue indicates a waiting or active sync, a green check means current, and a red X indicates an error. Virtual Files/File Provider mode uses different operating-system status indicators, so check the client window and Finder or Explorer details rather than assuming classic-mode icons apply.

If the number of pending items is falling, leave the client running and allow the scan to finish, especially after adding a large folder or reconnecting a device. If the same item remains at the top, open its error details. Record the local path and exact message before moving, renaming, or editing anything. Avoid repeatedly pausing and resuming while the queue is changing; it does not reveal the cause and can make progress harder to assess.

Check the file and ignored-file rules

When one file blocks progress, compare its name, path, and local state with the server copy in the Nextcloud web interface. Confirm that the file is not still open in an editor, being written by a camera or backup program, or locked by another process. If an application is actively changing the file, close it cleanly and let the client retry. Do not delete either copy simply to clear the status.

Some files are deliberately ignored. Nextcloud excludes certain system files and names that cannot be represented on other file systems. In the client settings, open Advanced → Edit Ignored Files (labels can vary by client release) and review custom patterns for the affected name or its parent folder. A wildcard such as * matches multiple characters; ? matches one character; a trailing slash limits a pattern to directories. Remove or narrow a custom rule only if the file should sync. Do not edit the global sync-exclude.lst shipped with the application as a first fix; Nextcloud warns that changing this file can cause unintended behavior.

Also check the client’s ignored or unsynced-folder status and selective-sync choices. A folder excluded intentionally will not become synchronized just because the client is restarted. If the problem affects only a particular path, temporarily testing a copy in a simple folder can help distinguish a path-specific rule from a general connection problem, but do not use a second cloud-sync service on the same live sync directory.

Separate a client problem from a server connection problem

Sign in to the same Nextcloud account in a browser and confirm that files and folders load. If the web interface works but every desktop device stalls, the server’s WebDAV endpoint or its configuration may be involved. The Nextcloud client uses WebDAV to access server files. For a server installed at https://cloud.example.com, its DAV endpoint is typically https://cloud.example.com/remote.php/dav; use your actual installation path. Opening that address in a browser should at least prompt for authentication or show a response from the endpoint. Authentication failures, certificate warnings, or server errors are signs to contact the administrator or inspect server logs rather than resetting the local client.

Check whether another synchronization program, backup utility, or offline-files feature is also managing the same directory. Nextcloud’s troubleshooting manual says that synchronizing one directory with multiple sync applications is unsupported and can risk data loss. Remove the overlap only after identifying which application owns the folder and preserving local changes. If only one computer is affected, check local disk space, folder permissions, antivirus or on-access scanning, and whether the client can read and rename files in the sync directory.

Restart, then collect a useful diagnostic

1. Wait for any active file operation to finish, then quit the desktop client from its tray or menu-bar menu. Start it again and watch whether the pending count changes.
2. If the client still stalls, open its settings and choose Advanced → Create Debug Archive… to save a diagnostic archive. The precise location of this control can vary by version and platform.
3. Review the log around the time the status stopped moving. Look for the affected path and a repeated error, such as access denied, a connection failure, or a filename restriction.

Debug archives include logs and database information and may contain sensitive filenames, account details, or server addresses. Review and redact them before sharing with support. The Nextcloud troubleshooting documentation describes the debug archive and other ways to capture client logs.

Use a database reset only for the matching error

Do not routinely delete the client’s sync database to fix a generic “Processing files” status. Nextcloud documents a narrower remedy for the specific “CSync unknown error”: stop the client, locate the hidden .sync_xxxxxxx.db file inside the account folder configured by the client, and remove that database before restarting. The documentation cautions that this also erases some settings about which files to download. Back up the local sync folder and record selective-sync settings first; never remove a database while the client is running. If the exact error is absent, inspect the debug archive or get support before trying this recovery.

Confirm synchronization has recovered

After the change, verify more than the disappearance of the spinner. The pending queue should drain, the client should show an up-to-date and connected state, and a small test file should appear in the expected location both locally and in the web interface. Confirm that the originally affected file has the intended contents and that selective-sync folders remain as configured. If the same file fails again, preserve its exact error and a redacted debug archive; a recurring permission, filename, WebDAV, or client-version problem needs a targeted fix.

For current client controls and troubleshooting steps, consult the Nextcloud Desktop Client user manual and the Nextcloud desktop troubleshooting documentation. The current online user manual is for Nextcloud 36; client labels and available Virtual Files features can differ by desktop-client release and operating system.