proton-drive-linux/docs/TROUBLESHOOTING.md

Troubleshooting

Start with pdfs diagnose, then find your symptom below. If nothing here helps, open an issue with the information listed under Reporting a problem.

• First checks
• Signing in
• The Proton Drive folder
• Uploads and sync
• Disk space
• Desktop integration
• Start over with a clean local state
• Reporting a problem

First checks

pdfs diagnose

Checks the installation and prints a report. It does not need the service, because the state worth diagnosing is often the one where the service will not start.

$ pdfs diagnose
Paths
[ok  ]   state dir: /home/you/.local/state/proton-drive-linux
[ok  ]   cache dir: /home/you/.cache/proton-drive-linux
[ok  ]   state dir writable: write and fsync succeeded
[ok  ]   database: /home/you/.local/state/proton-drive-linux/cache.db (473.1 MiB)

FUSE
[ok  ]   /dev/fuse: /dev/fuse
[ok  ]   unmount helper: fusermount3 or fusermount on PATH

Account
[ok  ]   keyring session: you@proton.me

Daemon
[ok  ]   control socket: /home/you/.local/state/proton-drive-linux/control.sock
[ok  ]   daemon responding
[ok  ]   active mount: /home/you/ProtonDrive (fuse.protondrive)
[ok  ]   network: online
[ok  ]   queued writes: none
[ok  ]   database integrity: SQLite integrity_check passed
[ok  ]   configured mountpoint: /home/you/ProtonDrive

No problems found.

It exits non-zero when a check fails, so it also works in a health-check script.

Logs

journalctl --user -u proton-drive.service -f           # follow the service
journalctl --user -u proton-drive.service -b -p warning  # warnings since boot

For more detail, raise the log level with a drop-in (see CONFIGURATION.md) and restart the service.

Service state

systemctl --user status proton-drive.service
pdfs status

Signing in

"Proton is asking for a CAPTCHA" — Proton wants human verification, usually on a VPN or an unfamiliar network. The CLI cannot show it. Sign in with pdfs-app, which displays the challenge; the stored session then works for the CLI too.

Sign-in works but is forgotten after a restart — no Secret Service provider is running, or its keyring is locked. Install and unlock GNOME Keyring, KWallet or KeePassXC (with Secret Service enabled). pdfs diagnose shows keyring session as failing in that case.

The Proton Drive folder

Tip

When the service hangs, any program that touches the Proton Drive folder can hang with it, including ls and your shell's prompt. Prefix exploratory commands with timeout 5.

Transport endpoint is not connected — the service stopped without unmounting. Unmount and restart:

fusermount3 -uz ~/ProtonDrive
systemctl --user restart proton-drive.service

The folder is empty or missing — check that the service runs and is signed in (pdfs status). The service waits for a stored session before it mounts.

Everything in the folder hangs — find out what the service is doing, then restart it:

timeout 10 pdfs diagnostics
systemctl --user restart proton-drive.service

The service watchdog restarts a service that stops answering for two minutes by itself. Attach the pdfs diagnostics output to a bug report; it shows which worker is stuck.

A change made on another device does not show up — changes arrive through Proton's event stream, normally within seconds. To fetch a folder again at once:

pdfs refresh Documents

"Permission denied" when writing — the item is in a share where you are a viewer, or under Shared with me/, which is read-only as a folder. Check your role with pdfs shared-with-me.

ln or another program fails with "Operation not permitted" — Proton Drive cannot store symbolic links, hard links, device files or FIFOs, so creating one fails at once. The error is intentional. Use a synced folder for projects that need them, or exclude those paths.

Uploads and sync

A change shows here but not on other devices — changes are recorded on this computer first and sent from a queue. List what is still waiting, and what needs attention:

pdfs sync queue
pdfs sync issues

The app shows the same on Sync → Overview. A change waits while the service is offline or sync is paused (pdfs status), and backs off after a failure. To retry at once:

pdfs sync retry           # every failed operation
pdfs sync retry 42        # one operation

A change Proton Drive refuses (storage full, access taken away, folder gone) is listed by pdfs sync issues with what to do. It stays queued until you fix the cause or drop it. Dropping it undoes it here; save a file's content first if you want to keep it:

pdfs sync export 42 ~/Desktop/
pdfs sync discard 42

If you suspect the local-first behaviour of 3.0.0 itself, "local_first": false in config.json makes the Proton Drive folder wait for Proton Drive again while online (see CONFIGURATION.md), and please report the problem.

A file in a synced folder does not upload — check that:

• it is not matched by .pdfsignore or ignore_patterns;
• no program still holds it open for writing (such files wait until closed);
• sync is not paused (pdfs status, tray);
• the folder has no error on Sync → Folders.

pdfs sync now starts a pass immediately.

Files named (sync-conflict …) appeared — the file changed in two places at once. Nothing was lost; see Conflicts to pick a version.

Photos show the wrong date after a Google Takeout import — run pdfs redate-photos --dry-run, see USER_GUIDE.md.

Disk space

What	Check	Reduce
Content cache	pdfs cache inspect	Lower Preferences → Storage → Cache size limit, or pdfs cache clear
Available-offline files	pdfs pins	pdfs unpin PATH
Metadata database	pdfs cache inspect (reclaimable)	pdfs cache vacuum
Synced folders	pdfs sync list	Switch large folders to online only: pdfs sync mode ID ondemand

pdfs cache vacuum locks the database while it runs and needs free space for a second copy of it.

Desktop integration

No tray icon on GNOME — install and enable the AppIndicator and KStatusNotifierItem Support extension. Other desktops show the icon natively. If you hid it from its own menu, turn it back on under Preferences → General → Appearance.

The search launcher does nothing — pdfs-prompt needs the service. Run it from a terminal to see its error. For --fzf, install fzf and a supported terminal.

The app shows "Not responding" — the service runs but does not answer within five seconds. See Everything in the folder hangs.

Start over with a clean local state

This removes the local database and cache so they are rebuilt from Proton Drive. It is the fix for a damaged database and the only way to downgrade to an older release.

Warning

Content in staging/ and recovery/ has not reached Proton Drive yet. Deleting it loses those changes permanently. Wait until pdfs sync queue is empty.

pdfs sync queue                                   # must list nothing
systemctl --user stop proton-drive.service
mv ~/.local/state/proton-drive-linux ~/.local/state/proton-drive-linux.bak
mv ~/.cache/proton-drive-linux ~/.cache/proton-drive-linux.bak
systemctl --user start proton-drive.service

Your session is in the keyring and your settings in ~/.config, so you stay signed in. Synced folders are not re-attached automatically; restore them with pdfs sync restore as described in RECOVERY.md. Delete the .bak directories once everything is back.

Reporting a problem

Include:

• pdfs --version, your distribution and desktop;
• the output of pdfs diagnose;
• relevant log lines from journalctl --user -u proton-drive.service;
• for a hang, the output of timeout 10 pdfs diagnostics;
• the steps that reproduce it.

Logs contain file names. Remove anything private before posting. Report security problems privately as described in SECURITY.md.