Diagnose a problem

Before working through the cases below, run:

It gathers, in one pass, what a support case needs and what the sections below otherwise ask you to collect by hand: the running daemon and its per-thread kernel wait-channels, the mount table, the FUSE connection’s waiting count, a timed check that the mountpoint still answers, the effective configuration, and — from the running daemon over a per-user socket — the engine’s own view of what each object is doing. A PASS/WARN/FAIL summary sits on top; the headline check is the one that matters most, and it is the reason doctor sometimes pauses for two seconds before it prints: it samples the mount twice.

No single instant can tell a wedged mount from a busy one. A request that is merely in flight has a reply parked for it from the moment it arrives, so waiting and the parked-reply total agree on any mount that is doing work. What separates the two is whether the work moves. If the same job — the same inode, intent and step — is still handed out to a worker two seconds later, or a reply is still parked with nothing running behind it at all, the mount has stopped answering and that is a FAIL. If the work moved on, it was load, and doctor says so. Both samples are printed in the ENGINE section, so the report shows its own evidence.

To send the result to us, write the bundle to files and attach them:

The report is redacted by default and safe to attach: the engine’s view is name-free (it speaks in inode numbers, never file names), no directory of the mount is ever listed, no secret is read (only the server and login, never the password), and the home path and username are masked in the text. The header states exactly what is and is not redacted. --no-logs omits the journal tail; --include-listing turns redaction off for a consenting deep dive.

Every probe is best-effort: one that cannot run says why, and the rest go on — so the report is still useful on a half-broken system, which is exactly when it is needed.

doctor answers is the mount healthy. When the question is what is happening to my files, use:

It names files, which is exactly why it is a separate command and not a flag on doctor: this output is for you, in your terminal, and there is no way to write it to a file for someone else.

The UPLOADS section is the one to check after saving something. It is read from the state database rather than from the daemon, so it is reported even when nothing is mounted, and it distinguishes three states: waiting (owed, the uploader will get to it), sending (on its way), and PARKED — an upload given up after a permanent failure such as a conflict, missing permissions or a full quota. A parked upload is the one case that needs you: the file reads as saved locally, it is not on the server, and nothing will retry it on its own. Your bytes are safe in the buffer either way.

DOWNLOADS separates the two things a user would call downloading: reading is a range being served live to whoever asked for it, caching is a whole-file hydration running in the background with nobody waiting for it. Individual reads last milliseconds, so a single run only catches a sample of them — wusel status --watch redraws once a second.

Both ride the session (user) D-Bus and both are fail-soft — without them the mount itself keeps working:

On success the daemon logs at startup:

A mount started from an SSH terminal on a desktop machine runs outside the graphical session’s environment (DBUS_SESSION_BUS_ADDRESS is not set there). Since systemd distributions share one user bus per user, the daemon falls back to it automatically ($XDG_RUNTIME_DIR/bus; the log then shows session bus found via XDG_RUNTIME_DIR) — SSH-started mounts integrate with the desktop out of the box.

If even that fails, the daemon warns (no session D-Bus — desktop integration disabled …); the manual override is:

Verify the channel end-to-end without mounting:

If the test notifications appear in the graphical session, conflict and error notices from the daemon will too.

The cloud-provider registration is missing on this machine (it is per-machine, not per-account-config): run the install-provider step from above, restart Nautilus, and check the startup log for the registered as a cloud provider line.

Historically two distinct causes; both are visible in the logs now:

Almost always the network, and the mount says so on its own: when the server stays unreachable for about ten seconds, a "Connection lost" notification names the server, and the file manager’s account status switches to error. A second notification announces the connection coming back. Both are localized; neither repeats while the outage lasts (one per incident, not one per failed request).

Two things follow from that, when a mount seems stuck:

The journal carries the detail in both cases — the failing URL and the reason ([connect] … dns error, [timeout] …):

wusel doctor also reports connectivity, and is the better first step if the mount answers to nothing at all.

To rule the cache out (or reset a tester’s machine to a fresh-connect state) without touching credentials or config:

Run it while the account is not mounted — including for a single path, where that requirement is a known limitation rather than a technical necessity. If a problem survives cache clear, it is not a caching problem.

An upload that loses against a newer server version keeps both files: the server version stays, the local edit is saved as name (conflicted copy <timestamp>).ext next to it. Expect

With text_merge enabled a clean 3-way merge is attempted first; it needs a cached base version of the file, otherwise it falls back to the conflicted copy.

Uploads are asynchronous by default: saving a file returns as soon as the change is safe on local disk, and the transfer to the server runs behind it. While it is on its way the file carries an uploading emblem; once it lands the emblem goes back to cached.

A sync-error emblem means the upload was refused for good — most often wrong permissions on the target, a name conflict, or a full quota (see the WARN … upload failed permanently log line and the desktop notification). The change is not lost: the bytes are kept locally, and saving the file again re-tries the upload once the cause is fixed. Transient problems (the server briefly down, a dropped connection) are not shown as errors — they retry on their own until they land.

To make saving wait for the upload and report its result directly — the pre-async behaviour — set [sync] upload = sync in config.toml.

If it is large files in particular that fail (small ones upload fine), the cause is usually a reverse proxy mishandling the chunked-upload endpoint — see Uploads fail, stall, or spawn conflicted copies.

wusel doctor (see First stop: wusel doctor) lists any objects still owed to the server and how their uploads stand.

Large files upload with Nextcloud’s chunked-upload protocol: many small PUT`s to `/remote.php/dav/uploads/, then one assembling MOVE. Almost every upload problem seen in the field has been a reverse proxy in front of Nextcloud mishandling that endpoint — not wusel or Nextcloud themselves. Work through the client switches first (no server access needed); then, if you administer the server, the proxy checks.

wusel already tolerates the most common proxy misbehaviour on its own: if the assembling MOVE returns an error (a proxy timeout surfaced as 403/5xx, or a WAF) but the file did assemble in full, the upload is counted as the success it is — no sync-error emblem, no conflicted copy. The switches below are for when uploads still fail or crawl.

The default is INFO: the production narrative (mount/unmount, the startup cache summary, uploads, push connection, conflicts, warnings, errors) without per-operation noise. More detail is opt-in via the RUST_LOG environment variable:

Foreground (a shell):

Production (the systemd user service): set the variable in a drop-in and restart —

Remove the drop-in (or the Environment= line) and restart to return to INFO.