Rescuing a Stuck Nextcloud Sync: Debugging Flatpak Clients and Server-Side Ghost Files

Nextcloud is a robust solution for self-hosted file synchronization and collaboration. However, because it relies heavily on a relational database to track the state of the physical filesystem, discrepancies between the two can occasionally occur. When the database believes a file exists but the physical disk disagrees, the synchronization engine can grind to a halt.

This post details a comprehensive, bottom-up debugging process to rescue a Nextcloud client stuck in an infinite synchronization loop. This specific scenario addresses a Linux desktop environment utilizing the Flatpak version of the Nextcloud client, communicating with a containerized Nextcloud server backend.

The symptom is common: the Nextcloud client icon remains in a perpetual state of "syncing" or displays a persistent error, completely blocking the synchronization queue. Resolving this requires tracing the error from the isolated local client logs all the way down to the server's database tables.

Phase 1: Client-Side Diagnostics in a Flatpak Environment

The first step in any synchronization failure is to consult the client logs. In a standard Linux installation, these might reside in ~/.config/Nextcloud/. However, Flatpak applications operate within sandboxed environments, meaning their configuration and log files are isolated.

To locate the Nextcloud Flatpak client logs, you must navigate to the specific application variable directory:

cd ~/.var/app/com.nextcloud.desktopclient.nextcloud/config/Nextcloud/logs/

Within this directory, you will find compressed historical logs and the current active log (e.g., 20260226_0612_nextcloud.log.0). Extracting and parsing these logs is critical for identifying the "ground zero" of the failure.

Use tools like grep or zgrep (for compressed logs) to filter for critical failures:

zgrep -i "FatalError" 20260226_0611_nextcloud.log.0.gz

In our scenario, the log output revealed a highly specific error:

Could not complete propagation of "Talk/Contract_Document_(2).docx" by OCC::PropagateDownloadFile with status OCC::SyncFileItem::FatalError and error: "Failed to write file contents: File by id 2070874 not found"

Additionally, the logs showed the server returning an HTTP 503 Service Unavailable status code for this specific file.

This log entry is the most crucial piece of information in the entire investigation. It tells us three things:

1. The exact local path the client is attempting to sync.
2. The nature of the failure (a download propagation error resulting in a 503 status).
3. The internal database identifier (fileid 2070874).

Because this is categorized as a FatalError, the Nextcloud client suspends the rest of the synchronization queue to prevent data corruption.

Phase 2: Server-Side Filesystem Validation

With the problematic file identified, the investigation shifts to the server. The objective is to determine if the file physically exists on the disk. Given that the server architecture relies on Docker containers, you must access the specific container handling the web server and PHP execution.

First, determine the absolute path of the Nextcloud data directory. Do not assume the default paths, as custom Docker volumes often alter this. Run the Nextcloud command-line interface (occ) to query the configuration:

sudo docker exec -u www-data nextcloud_web php occ config:system:get datadirectory

Assuming the output is /mnt/data, proceed to search the physical filesystem for the file the client is requesting:

sudo docker exec nextcloud_web find /mnt/data/anduin/files -name '*Contract_Document*'

In this debug scenario, the search yielded the original file, but not the duplicated (2) version the client was attempting to download. This confirms a classic "Ghost File" anomaly: a severe desynchronization between the database logic layer and the physical storage layer. The database is instructing the client to download a file that no longer exists on the hard drive. Consequently, when the Nextcloud PHP engine attempts to read the physical file to stream it to the client, the I/O operation fails, resulting in the 503 Service Unavailable error.

Running a standard occ files:scan at this point will likely fail to resolve the issue. The scanner is designed to index existing physical files into the database; it is notoriously poor at pruning complex, broken relational links—especially those involving shared files or third-party applications like Group Folders.

Phase 3: Database Autopsy and Logic Tracing

To understand why the server is hallucinating a file, you must dissect the database. Connect to the MariaDB or MySQL container:

sudo docker exec -it nextcloud_db mysql -u nextcloud -p nextcloud

Nextcloud's file tracking relies primarily on the oc_filecache table. Since we extracted the exact fileid (2070874) from the Flatpak client logs, we can bypass generic name searches and query the primary key directly:

SELECT fileid, storage, path, name FROM oc_filecache WHERE fileid = 2070874;

The result of this query is often revealing. In this instance, the query returned:

This exposes the root cause. The file had been deleted and moved to the internal trash bin of a Group Folder (__groupfolders/trash/). Furthermore, its physical filename had been mangled into unrecognized encoding (???????), likely due to path length limitations, special characters, or a bug within the Group Folders application itself during the deletion process.

But why was this trashed, mangled file blocking a specific user's synchronization queue? To answer this, we must inspect the oc_share table to understand the relational mapping:

SELECT * FROM oc_share WHERE item_source = 2070874 OR file_source = 2070874;

This query revealed that the deleted file ID was still actively linked via a share record to the user's personal /Talk directory.

The Bug Mechanism:

1. User A shared a file from a Group Folder to User B.
2. The file was subsequently deleted or manipulated, moving it to the Group Folder's hidden trash bin.
3. The Nextcloud Group Folders application failed to properly cascade this deletion to the oc_share table.
4. User B's client queries the server. The server checks oc_share, sees the active link to file ID 2070874, looks up the ID in oc_filecache, and attempts to serve the file from the corrupted trash path. The physical read fails, triggering the 503 error and halting the client.

Phase 4: Surgical Resolution

Since standard occ commands (files:scan, files:cleanup, groupfolders:trashbin:cleanup) are often ineffective against database inconsistencies of this nature, manual surgical intervention at the database level is required.

Disclaimer: Directly modifying the Nextcloud database is dangerous and can lead to severe data loss if executed incorrectly. Always ensure you have a complete database dump before proceeding.

To break the infinite loop, the ghost records must be eradicated. Execute the DELETE statements within the MySQL console:

1. Remove the Ghost File Record:

DELETE FROM oc_filecache WHERE fileid = 2070874;

2. Sever the Broken Share Links:

DELETE FROM oc_share WHERE item_source = 2070874 OR file_source = 2070874;

By removing these records, you eliminate the logical paradox. The server will no longer believe the file exists, and it will no longer attempt to force the client to download it.

Phase 5: Re-synchronization and Verification

After the database surgery is complete, you must force the Nextcloud engine to reconcile its internal state with the physical disk. Exit the database container and return to the web container to execute a targeted file scan for the affected user:

sudo docker exec -u www-data nextcloud_web php occ files:scan target_username

This process will traverse the user's directory, update the oc_filecache table legitimately, and output a summary of updated, removed, and new files.

Because the problematic file ID and its associated share have been purged, the server will naturally omit it from the subsequent synchronization payload sent to the client.

Without any further intervention required on the desktop environment, the Flatpak Nextcloud client will initiate its next scheduled polling cycle (usually within a minute). It will receive the corrected, sanitized state from the server, clear the FatalError flag, and resume synchronizing the remainder of the queue successfully.

Conclusion

Nextcloud synchronization failures, particularly those returning 503 errors on specific files, are rarely issues with the client software itself—whether installed natively or via Flatpak. They are almost exclusively symptoms of server-side database corruption, often triggered by complex interactions between third-party applications like Group Folders and the core sharing mechanisms.

When encountering a stuck sync queue, immediately dive into the client logs to extract the exact File ID. Using that ID to cross-reference the oc_filecache and oc_share tables is the most precise and efficient method to identify and surgically remove the anomaly, restoring harmony to the synchronization matrix.