From 5911e4b425c6a116909d85c9f5af9fcc43cd30c2 Mon Sep 17 00:00:00 2001
From: 5bentz <10729484+5bentz@users.noreply.github.com>
Date: Sun, 3 Jun 2018 09:39:14 +0200
Subject: [PATCH] Doc: Add Troubleshooting section

It provides guidelines to fix the following issues:
  - Script execution failed
    * Remove old installations
    * Reinstall
    * Check the host-app is installed correctly
  - PassFF is not working and takes 99% CPU
    * Check the PATH variable
---
 README.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/README.md b/README.md
index cbc0004..4c14c6e 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,41 @@ If this doesn't work, you can link the files yourself. First, change the `path`
     - Per-user: `~/Library/Application Support/Vivaldi/NativeMessagingHosts/passff.json`
     - System-wide: `/Library/Application Support/Vivaldi/NativeMessagingHosts/passff.json`
 
+### Troubleshooting
+
+#### Script execution failed
+#### Connection to the host app failed or returned an unexpected result
+
+> Connection to the host app failed or returned an unexpected result!
+> Make sure you have the latest version of the PassFF host app installed by following the installation instructions on GitHub.
+
+> Script execution failed.
+
+You get one of these error messages? Follow the instructions below!
+
+###### Remove old installations
+*Inappropriate installations can override another one that could work. So, it is simpler to remove everything and restart from scratch.*
+* Delete any file `passff.json` in the folders `native-messaging-hosts` and `NativeMessagingHosts`
+  * For the complete paths of these folders for your OS and browser, see the section above.
+* Verify all `passff.json` are deleted by doing a search.
+  * Use your best file searching tool. For example: `find / -type f -name 'passff.json'`
+
+###### Reinstall the host application
+See the section above.
+
+###### Check that the host application is correctly installed
+* Make sure the file `passff.py` is executable
+  * `ls -l /path/to/passff.py`
+* Open `passff.json` and verify `path` is set to the absolute path of the host executable `passff.py`: for example `"path": "/path/to/passff.py"`
+
+#### PassFF's host application is not working and takes 99% CPU
+
+###### Set a correct PATH in the `passff.py` script
+When the PATH variable is not set correctly, `pass` will complain about not finding `getopt` and then loop forever. You can reproduce this behavior on the command line:
+```
+PATH="$(which bash | xargs dirname)" $(which pass)
+```
+
 ### Preferences
 By modifying the `preferences section` in `passff.py` you will be able to set
   - the path to the `pass` script,