summaryrefslogtreecommitdiffstats
path: root/content/en/hardenedpass/reference/troubleshooting
diff options
context:
space:
mode:
Diffstat (limited to 'content/en/hardenedpass/reference/troubleshooting')
-rw-r--r--content/en/hardenedpass/reference/troubleshooting/index.md76
1 files changed, 72 insertions, 4 deletions
diff --git a/content/en/hardenedpass/reference/troubleshooting/index.md b/content/en/hardenedpass/reference/troubleshooting/index.md
index 4221c83..3dfce92 100644
--- a/content/en/hardenedpass/reference/troubleshooting/index.md
+++ b/content/en/hardenedpass/reference/troubleshooting/index.md
@@ -1,13 +1,81 @@
+++
title = "Troubleshooting"
date = 2026-11-05T00:00:00Z
-description = ""
+description = "Common HardenedPass errors, what they mean and how to fix them: passphrase, keys, SSH, push rejected, detached head, autofill."
weight = 110
draft = true
+++
-Placeholder.
+## Keys and passphrases
-## First heading
+**The app asks for the passphrase again and says it is wrong.** The passphrase does not
+match the private key. If you changed the key's passphrase on a computer, the app
+needs the new one. If caching is on, it asks again and replaces the old value.
-Text.
+**`Failed to import PGP key`.** The file is not a key the app can use. Keys without an
+encryption subkey are rejected, because they could not decrypt anything. Check that you
+exported the **private** key, with `gpg --armor --export-secret-keys`.
+
+**An entry will not open and no key matches.** The store is encrypted for a key that is
+not imported. Compare **Store recipients** on the import screen, or the `.gpg-id` file,
+with the keys in **Key manager**. A public key alone cannot decrypt: import the private
+one.
+
+**The key is on a smartcard.** GnuPG exports a stub for such a key, with no secret
+material in it. The app cannot decrypt with that. It needs the real private key.
+
+**`Found .gpg-id, but it contains an invalid key ID, fingerprint or user ID`.** The
+`.gpg-id` file has something the app does not understand. Check it on a computer: one
+key ID, fingerprint or address per line.
+
+## Connecting
+
+**`The provided repository URL is not valid`.** See the address forms in
+[Connect the app]({{< relref "/hardenedpass/getting-started/connect" >}}).
+
+**`Wrong password` or `Wrong passphrase`.** For a repository password or an SSH key's
+passphrase. Many hosting services want an access token rather than the account password.
+
+**`Selected file does not appear to be an SSH private key`.** You picked the public key,
+or a file in another format. Choose the file without `.pub`.
+
+**The sync fails after the server was reinstalled or moved.** Its host key changed. If
+you are sure why, use **Clear saved host key** on the repository screen, under **Edit
+Git server settings**. If you are not, treat it as an attack until you know better.
+
+**SSH login is refused.** Check that the public key is on the server, for the right
+account. **View generated public SSH key** shows it for a key made on the phone.
+
+## Syncing
+
+**`Push was rejected by remote, run pull before pushing again`.** The server has commits
+you do not have. Use **Synchronize repository**, which pulls and then pushes.
+
+**`Pull has failed, you're in a detached head`.** A conflict stopped the rebase.
+[Sync]({{< relref "/hardenedpass/using/sync" >}}) has the steps.
+
+**`Merge has failed, you're in a conflicting state`.** The same conflict, with **Rebase
+on pull** off. The way out is the hard reset in
+[Sync]({{< relref "/hardenedpass/using/sync" >}}), after saving anything you need.
+
+**`The repository must be cloned before syncing changes`.** The store on the phone has no
+remote. Set one under **Edit Git server settings** and clone it.
+
+## Autofill
+
+**No suggestions appear.** Check that HardenedPass is the selected autofill service in
+Android's settings, and that the browser is on the list in
+[Autofill]({{< relref "/hardenedpass/using/autofill" >}}).
+
+**Only the password gets filled.** That is the browser's support level, as with Vanadium.
+
+**`This app is currently not supported`.** The app cannot save from there. You can still
+add the entry by hand.
+
+**Nothing happens after tapping Save.** Android 14 and later hold back background
+windows, and the app has a workaround: update to the latest version.
+
+## Still stuck?
+
+Open an issue on the [tracker](https://github.com/danixland/HardenedPass/issues). Say
+which version you run and what you did. Never paste passwords, keys or real entry names.