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.

When you are signed in but the service does not answer, it also asks Proton which of your keys open, under Keys: each account key, each address key, and the address key your My Files share is encrypted to. A key that does not open is named with the key it depends on. The section shows key IDs, which are not secret, so you can post it in an issue.

$ 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. pdfs login prints the verification page's address: open it in your browser, complete it, then press Enter. The app shows the page in its own window.

"Verify in Your Browser" — WebKit, which shows the CAPTCHA page in the app, could not start its sandbox. Hardened systems such as secureblue keep its bubblewrap from the journal socket, and the log then shows bwrap: Can't get type of source /run/systemd/journal/socket: Permission denied and Failed to fully launch dbus-proxy. Choose Open Verification Page, complete the page in your browser, then choose Continue. If that sign-in is refused too, check that bwrap and xdg-dbus-proxy are installed. As a last resort, sign in once with the sandbox switched off for this one run:

WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS=1 pdfs-app

Quit the app first, so this starts a new instance. The page then runs without WebKit's isolation, so use this only for the sign-in. The stored session keeps working without it. Signing in from your usual network, without a VPN, often avoids the CAPTCHA in the first place.

"This version of the app is no longer supported" or "Proton is temporarily refusing sign-in from this device" — Proton blocks sign-in for a while after too many attempts or from a network it distrusts, and sends the first message even when the release is current. Do not retry for several hours, up to a day, then sign in once. If it still fails, run RUST_LOG=debug pdfs login and look for code= in the proton api request failed line: 2028 is this block, 5003 is a release Proton no longer accepts.

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. When the app finds a saved sign-in it cannot read, it says so above the sign-in form and opens on its own once the keyring is unlocked. You don't have to sign in again.

Asked for the mailbox password after every reboot — the account has a separate mailbox password (two-password mode). Such accounts are locked by default: the unlock lasts until you log out or restart. To stay unlocked, turn on Keep unlocked on this computer in the unlock dialog, or run pdfs unlock --remember. Either one stores the unlock in the system keyring. SECURITY_MODEL.md explains what that trades away.

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

fetch My Files root: … failed to decrypt: missing key in the service log — the account keys cannot open your Drive volume, which happens after a password reset. Proton locks the volume that was encrypted to the old keys. From 3.4.1 the client starts a new, empty My Files volume in that case. Your old files stay in the locked volume: open drive.proton.me and restore them there with your previous password. If the volume is not locked and the error stays, run pdfs diagnose and post its Keys section in an issue.

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.