nvrl/proton-drive-linux
1
0 Fork 0
mirror of https://github.com/narrrl/proton-drive-linux.git synced 2026-11-03 16:41:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: publish docs/ to the GitHub wiki and reorganise the user guide

Browse Source 
- scripts/publish-wiki.sh publishes every page listed in SECTIONS, copies
  images, writes a sectioned sidebar and footer, and removes stale pages.
  --check fails on links to missing files or headings and on docs pages
  that are neither published nor excluded.
- New wiki.yml runs the check on pull requests and pushes to main, and
  publishes when release.yml calls it or when started by hand.
- Split USER_GUIDE.md into topic pages (files, synced folders, photos,
  sharing, computers, launcher and tray); add Getting started and FAQ.
- Make the COPR repository the main Fedora path, with update and
  uninstall steps for every package type.
- Fix the stale CAPTCHA note in CLI.md, document pdfs unlock and lock,
  and drop the broken AGENTS.md link from CONTRIBUTING.md.
This commit is contained in:
nvrl committed 2026-10-17 13:57:55 +02:00
1 parent d1d4d23dd5
commit 9c30ff8276
24 files changed
+1503 -724
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/TROUBLESHOOTING.md
+128 -84
View File
@@ -57,7 +57,7 @@ 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](CONFIGURATION.md#the-systemd-service)) and restart the service.
[Configuration](CONFIGURATION.md#the-systemd-service)) and restart the service.
### Service state
@@ -68,96 +68,123 @@ 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.
### Proton is asking for a CAPTCHA
**"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:
Proton wants to check that you are human, usually on a VPN or an unfamiliar network. The app
shows the page in its own window. `pdfs login` prints the page's address instead: open it in your
browser, complete it, then press Enter.
### "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 away from the journal socket. The log then shows
`bwrap: Can't get type of source /run/systemd/journal/socket: Permission denied` and
`Failed to fully launch dbus-proxy`.
1. Choose **Open Verification Page** and complete the page in your browser.
2. Choose **Continue**.
If that sign-in is refused too, check that `bwrap` and `xdg-dbus-proxy` are installed. As a last
resort, quit the app and sign in once with the sandbox switched off for this one run:
```bash
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.
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.
### "This version of the app is no longer supported" or "Proton is temporarily refusing sign-in from this device"
**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.
Proton blocks sign-in for a while after too many attempts, or from a network it distrusts. It sends
the first message even when your version is current. Do not retry for several hours, up to a day,
then sign in once.
**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](SECURITY_MODEL.md) explains what that trades away.
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 turned on). `pdfs diagnose` then shows
`keyring session` as failing.
When the app finds a saved sign-in it cannot read, it says so above the sign-in form, and opens
by itself once the keyring is unlocked. You do not 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. The [security model](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`.
> including `ls` and your shell's prompt. Put `timeout 5` in front of commands you try.
**`Transport endpoint is not connected`** — the service stopped without unmounting. Unmount and
restart:
### `Transport endpoint is not connected`
The service stopped without unmounting. Unmount and restart:
```bash
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](https://drive.proton.me)
and restore them there with your previous password.
### The folder is empty or missing
**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.
Check that the service runs and is signed in, with `pdfs status`. The service waits for a stored
session before it shows your files.
**Everything in the folder hangs** — find out what the service is doing, then restart it:
### `fetch My Files root: … failed to decrypt: missing key` in the log
Your account keys cannot open your Drive, which happens after a password reset: Proton locks the
files that were encrypted with the old keys. Since 3.4.1 the client then starts a new, empty My
files. Your old files are still there, locked: open [drive.proton.me](https://drive.proton.me) and
restore them with your previous password.
### Everything in the folder hangs
Find out what the service is doing, then restart it:
```bash
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.
The service restarts by itself when it stops answering for two minutes. Attach the
`pdfs diagnostics` output to a bug report; it shows which part 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:
### A change made on another device does not show up
Changes from other devices normally arrive within seconds. To fetch a folder again at once:
```bash
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`.
### "Permission denied" when writing
**`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.
The item is in a share where you are a viewer, or directly under `Shared with me/`, which is
read-only. 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. This is on purpose. For projects that need them, use a
[synced folder](SYNCED_FOLDERS.md) and 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:
### 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 you:
```bash
pdfs sync queue
@@ -165,72 +192,89 @@ 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:
sync is paused (`pdfs status`), and waits longer after each failure. To retry at once:
```bash
pdfs sync retry # every failed operation
pdfs sync retry 42 # one operation
pdfs sync retry # every failed change
pdfs sync retry 42 # one change
```
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:
it undoes it here, so save a file's content first if you want to keep it:
```bash
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](CONFIGURATION.md#local_first)), and please report the problem.
[Changes waiting for Proton Drive](SYNCED_FOLDERS.md#changes-waiting-for-proton-drive) explains
the choices.
**A file in a synced folder does not upload** — check that:
If you suspect that the instant, queued changes introduced in 3.0.0 are the problem,
`"local_first": false` in `config.json` makes the Proton Drive folder wait for Proton Drive again
while online (see [Configuration](CONFIGURATION.md#local_first)). Please report the problem too.
- it is not matched by `.pdfsignore` or `ignore_patterns`;
### A file in a synced folder does not upload
Check that:
- it is not excluded 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**.
- sync is not paused (`pdfs status`, or the tray);
- the folder shows no error on **Sync → Folders**.
`pdfs sync now` starts a pass immediately.
`pdfs sync now` starts a sync pass at once.
**Files named `(sync-conflict …)` appeared** — the file changed in two places at once. Nothing was
lost; see [Conflicts](USER_GUIDE.md#conflicts) to pick a version.
### Files named `(sync-conflict …)` appeared
**Photos show the wrong date after a Google Takeout import** — run
`pdfs redate-photos --dry-run`, see [USER_GUIDE.md](USER_GUIDE.md#importing-from-google-photos).
The file changed in two places at once. Nothing was lost. See
[Conflicts](SYNCED_FOLDERS.md#conflicts) to pick a version.
### Photos show the wrong date after a Google Takeout import
Run `pdfs redate-photos --dry-run`. See
[Fixing photos filed under the wrong date](PHOTOS.md#fixing-photos-filed-under-the-wrong-date).
## Disk space
| What | Check | Reduce |
|---|---|---|
| Content cache | `pdfs cache inspect` | Lower **Preferences → Storage → Cache size limit**, or `pdfs cache clear` |
| Cache of opened files | `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.
`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**.
### No tray icon on GNOME
**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.
Install and turn on the
[AppIndicator and KStatusNotifierItem Support](https://extensions.gnome.org/extension/615/appindicator-support/)
extension. Other desktops show the icon without help. If you hid it from its own menu, turn it
back on under **Preferences → General → Appearance**.
**The app shows "Not responding"** — the service runs but does not answer within five seconds.
See [Everything in the folder hangs](#the-proton-drive-folder).
### 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](#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.
This removes the local database and cache, so they are built again from Proton Drive. It fixes a
damaged database, and it is the only way to go back 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.
> changes for good. Wait until `pdfs sync queue` is empty.
```bash
pdfs sync queue # must list nothing
@@ -241,8 +285,8 @@ 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](RECOVERY.md#2-restore-your-synced-folders). Delete the `.bak` directories once
folders are not attached again by themselves. Restore them with `pdfs sync restore`, as described
in [Recovery](RECOVERY.md#2-restore-your-synced-folders). Delete the `.bak` directories once
everything is back.
## Reporting a problem
@@ -253,7 +297,7 @@ Include:
- 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.
- the steps that make it happen.
Logs contain file names. Remove anything private before posting. Report security problems
privately as described in [SECURITY.md](../SECURITY.md).
privately, as described in [SECURITY.md](../SECURITY.md).