Troubleshooting

Something not behaving? Start with the Desktop App's Diagnostics panel, or run the standalone report:

swarmfile-doctor --json --report doctor-report.json

It checks the engine, DNS, the hub, the sign-in token, cloud storage, the peer-to-peer network, mDNS, the firewall, and the mount itself, and its exit code is a verdict (0 all passed, 1 a failure, 2 warnings only). Most problems below show up there by name, and its output is the first thing support will ask for. See swarmfile-doctor for every flag.

The drive isn't there#

Windows default drive letter changed. If the usual letter was taken at startup, Swarmfile picks the next free one - that is per-machine and runtime-determined. Read the actual location from the Desktop App's Status/rail entry rather than expecting a fixed letter.
The boot mount's drive letter is held by something else. The failure card offers Use another drive letter - it forgets any explicit letter you set and reconnects, so Swarmfile picks a free one; no config.json edit or manual relaunch needed. Open Another Drive… stays available too, for working at a different letter (or an empty folder) right now, without restarting. If the letter comes from SWARMFILE_MOUNT_POINT on that machine, the action refuses and says so - change the environment variable instead. If every letter is taken, choose an empty folder instead - auto has nothing left to pick.
A second mount failed. Windows cannot mount over a folder that already has files in it: pick an empty folder, or let swarmfile mounts open auto choose the next free drive letter. A drive letter something else holds is refused with a message naming what holds it. From the CLI, swarmfile mounts list shows every open mount and swarmfile mounts open <path> --label "…" opens another.
The mount was healthy and stopped answering. The drive is mounted to wait rather than fail mid-write, so a stalled mount looks like a hung Finder/Explorer window instead of an error. Open Settings → Diagnostics and use Repair drive (not available on Linux); it reconnects in seconds without touching your queued uploads. The full background is in If the drive stops responding.
The drive has never appeared and the app says the config file is broken. A syntax error in config.json drops the whole file, including org_id/project_id, so status names the file and the parse position instead of asking you to pick a project. Fix the JSON and restart Swarmfile - see Engine Config File.
Access is still being granted. A project you have just been added to (or your account's first device) shows its drive only once its encryption key reaches this machine - for an end-to-end-encrypted project that means another member's client, or your org's granter (about a five-minute cadence at worst), has wrapped the key to it - and if no grant was ever queued, your engine asks the hub to open one itself. A running engine watches for the grant on its own and mounts the drive as soon as it lands, so leave the app open and let it finish rather than reinstalling or re-adding the project; Recent issues in Diagnostics shows the wait. See End-to-End Encryption.
macOS/Linux: the mount is a folder, and on a machine that has never mounted anything the engine may still be finishing startup. Give it a moment, then check Diagnostics.

A file won't open, or opens very slowly#

First open pays for the network. Opening a file you've never read streams from a LAN peer if one has it, otherwise from the cloud; the Desktop App's Status shows peer counts, and swarmfile status prints the same. If peers exist but transfers never come from the LAN, run the doctor - the mdns listen and host firewall checks name the cause.
macOS is silently denying local network access. On macOS 15+, the engine needs Local Network consent (System Settings → Privacy & Security → Local Network) to find peers on your LAN. The doctor's macos local network check says so explicitly when a LAN connection fails for that reason, and that row in Settings → Diagnostics offers Open Local Network settings to take you straight there.
Corporate Wi-Fi blocks mDNS. Discovery is multicast; on a VLAN or Docker bridge it may be blocked even though the hub is reachable. Set an office grouping (swarmfile office set <name> --lan-from-office) so same-office peers are treated as LAN anyway - see Network Requirements.
If it's a wait, not an error. A version that has never finished uploading can be opened; reads that outrun the upload return a retryable "try again" rather than an I/O error, deliberately, so applications don't mistake a slow upload for a damaged file. For the part you actually need, ask for it first: swarmfile fetch <path> --tail 209715200, or follow a moving viewer with --follow - see Working with Files.
Every file fails, not just one. If opens across a whole folder or drive return I/O errors while the listing still looks fine, the engine treats it as a stale key or access problem: it notices the pattern and refreshes the project's key and scope in place, and the files start opening again within a minute or two - no restart needed. Recent issues (Status/Diagnostics) shows the automatic refresh while it happens. If it is still failing after a couple of minutes, restart Swarmfile; that is the last resort, not the first step.

Writes are refused, or an app reports a plain I/O error#

A filesystem can't say "someone else changed this too", so blocked writes look like ordinary I/O errors to applications. The Desktop App remembers why: click the Status pill and read "Why did my save fail?" - it lists recent refusals with the file's path, the reason, and how many times it happened (the engine keeps the last 64). Match the cause:

Unresolved conflict - the same file changed in two places. The file shows as read-only (macOS/Linux) and saves fail with "permission denied" ("access denied" on Windows) rather than an I/O error. swarmfile conflicts lists them; resolve with swarmfile conflicts resolve <path> --auto (or --winner local|remote|keep-both). See Branches & Merging.
Someone else holds the file - swarmfile locks shows who, and swarmfile unlock-request create <path> asks them to release it. See Entry locks.
A Pack & Go lease lapsed while you were offline - the reservation expired (leases only renew while online). Re-run swarmfile offline prepare when you have connectivity; see Working Offline (Pack & Go).
A bulk Pack & Go reservation covers the file - a single-file lock and a scope reservation both refuse writes with locked, but a scope reservation blocks checkout/restore/merge too, not just saves. Its owner releases it with swarmfile offline return; see Working Offline (Pack & Go).
A native worksharing tool has the file open elsewhere - the Desktop App notification names who and which machine. See Worksharing.
The file is still being created (pending_create) - a lock, comment, share, or ACL action on a file whose first upload hasn't reached the hub yet. This one is a hub 409 rather than a filesystem refusal, so it won't appear in "Why did my save fail?"; the Desktop App badge says "still being created". Wait a moment and retry, or check swarmfile status → pendingCreates.
You're offline and the file isn't in your reserved scope (offline) - the drive is offline and this path wasn't covered by an offline reservation. Reconnect, or include it the next time you run swarmfile offline prepare.
This computer is quarantined (quarantined) - the account was suspended after a burst of changes that looked like ransomware; an org owner clears it from Settings → Quarantine. On macOS and Linux, reads keep working and only writes are refused; on Windows the drive stays mounted and saves are accepted locally but simply don't sync until it's cleared. Already-queued saves are held, not lost - they resume once it's cleared. See Security.
Another machine is still uploading the file (uploading_elsewhere) - its first upload is still in flight from wherever it was created; wait for that to finish.
Another drive on this computer has the file open (locked_by_mount) - with exclusive-write mode, a drive refuses a sibling drive's write - and its rename, delete, or replace of that file - while it holds it (on Windows the write-open itself fails as "file in use"); the reason names the holding drive. Close the file there, or wait for that drive's save to finish.
Folder not empty - deleting a folder that still contains files is refused on purpose. Empty it first.
Pack & Go disabled by policy - an administrator can disable bulk offline reservation with SWARMFILE_PACK_AND_GO_POLICY=disabled on the engine; the CLI reports pack_and_go_disabled. If the value was meant to be different, check its spelling: an unrecognized value disables Pack & Go and now warns at startup and in swarmfile-doctor.

Files aren't syncing#

The Desktop App header always reports the truth: Syncing N, Synced, or one of the attention states below.

Waiting on plan - the hub is refusing saves on plan grounds, usually because the organization's storage allowance is full. Raise the limit or free space; retries resume automatically. The plan panel shows the allowance.
N changes not syncing - the hub keeps refusing these saves for another reason. They're safe on this computer and Swarmfile keeps trying. swarmfile sync stuck lists each file, why, and since when; swarmfile sync discard <entry-id> drops the local change and returns the file to its cloud version (it asks first, and it cannot be undone).
This computer is quarantined - the account was blocked after a burst of changes that looked like ransomware. On Windows the drive stays mounted and saves are accepted locally but don't sync; on macOS and Linux writes are refused. An org owner or admin clears it from Settings → Quarantine, and queued work resumes on its own. See Ransomware quarantine.
N changes failed - work stopped retrying. The banner offers Retry; saving the file again also works.
A file was never supposed to sync - check the exclusion rules: swarmfile check-ignore <path> says whether a path is ignored and by which .gitignore/.swarmfileignore rule. To remove already-synced, now-ignored content, swarmfile ignore-clean (soft delete, recoverable from Trash).
Signed out - a lapsed sign-in pauses the queue without burning retries; sign back in and it drains. The doctor's oidc token check reports it directly.

Uploads are slow (very large file)#

Saving never waits for the upload: the write returns at local-disk speed and the durable queue drains in the background. A multi-hundred-gigabyte save on a modest uplink can legitimately take days. To see what's live, swarmfile uploads lists every in-flight upload on the mount (yours and other machines'); --wait blocks until none remain, which is handy before a checkout in CI. While a file is uploading, other people can fetch the part they need first - see While a large file is still uploading.

The same is true of many files at once: a mass edit or overwrite of hundreds of small files is paced to your plan's request allowance and can take minutes to reach Synced - see Uploads are designed not to block.

Storage says full#

Storage is enforced per organization, and a Free plan's allowance is a hard stop rather than a bill. Free space (swarmfile hydrate free-space, or Free up space in the Desktop App) or move the organization to a paid plan; the Billing & Plans page explains the allowance, overage, and where to change it.

Search returns nothing#

Search queries a local metadata cache first, then the hub, so a file you've never seen in this project may not appear until the hub is reachable - and it covers names and paths, not full file contents. See Search.

An update didn't happen#

Updates are never installed silently. The Desktop App checks for a new version at startup and periodically, and a found update only shows as a pill in the header plus a card in Diagnostics; Install now is the only path that installs it. If the pill has sat uninstalled for a week, you'll also see a one-time desktop notification reminding you - still no automatic install. If an update won't take, use Diagnostics → Reinstall… for a full reinstall that keeps your queued uploads. On Windows, the doctor's updater-helper-task check reports whether the updater helper is registered; swarmfile-doctor --repair does the same full reinstall headlessly.

Signing in#

A message like "You may need to sign in again" means the session's refresh token expired or was revoked - sign in again and queued work resumes.
SSO: enter your organization's slug (the short name in your org's Swarmfile URL). There's no email-domain auto-detection, so a personal email alone won't route to your IdP.
A machine that can't sign in at all can still be diagnosed: swarmfile-doctor runs without an engine or a session.

"A file is still uploading" when branching or merging#

branch create, merge, checking out or locking a file, and copying one are refused with entry_uploading while a file they'd pick up is still uploading. Taken mid-upload, they would silently use the file's previous version and still look complete. Usually you just wait for the upload to finish and retry. swarmfile status on the machine doing the writing shows its queue.

If that machine crashed or went offline mid-upload, restart Swarmfile on it: its queue picks up where it stopped and finishes the upload. If the machine can't come back, the stuck upload stops blocking branch creates, merges from its branch, and copies once it has sent no progress report for 30 minutes. Pausing sync doesn't count as silence: a paused machine keeps reporting, so its uploads still hold. Locking or checking out that file, and a merge that would change the file itself, keep waiting for up to six hours: taking them early would refuse the upload if its machine comes back. To clear the pointer explicitly - so readers stop waiting on it too - swarmfile uploads retract <path> (needs write access to the file; retracting a live upload is a no-op).

A merge won't finish#

A large merge applies in the background once the hub accepts it - the command or app reports success before every file has landed, and swarmfile merge --wait blocks until it finishes. If one looks stuck:

Check the doctor. The merges in progress check lists in-progress merges with their age and flags any past the hub's stuck grace, at which point the hub's own sweep rolls the merge back.
stale_merge is not stuck. That refusal means the target branch moved after the merge was prepared; run merge again. It either lands cleanly or comes back with the genuine conflict that race exposed, which the normal resolution flow handles.
A project owner can repair a genuinely stuck one. The hub's branches/merge/repair route resumes a merge whose worker stopped, or rolls it back (forced rollback is owner/admin-only). Nothing is lost either way: entries already applied stay, and a follow-up merge picks up whatever is still divergent.

Getting help#

When you contact support, include:

swarmfile-doctor --json --report doctor-report.json (attach the JSON file).
What you did, what you expected, and what happened - with the exact time and timezone.
Whether it happens on one machine or everyone's, and on one file/folder or everywhere.

See Operations for admin-side diagnostics and connectivity checks, and Network Requirements if your firewall or proxy team needs the full list of hosts and ports.