Skip to content

Troubleshooting guide

Jump to bottom
Sami Vänttinen edited this page Mar 6, 2023 · 39 revisions

Here's a general checklist for KeePassXC-Browser related connection issues. Make sure you have read the basic Getting Started documentation for the browser extension.

1) After enabling Browser Integration and support for your browser

When you encounter connection problems, you may have installed the extension with a fork of e.g. Firefox or Chromium. In this case consult the section "Other browsers". Depending on the operating system the org.keepassxc.keepassxc_browser.json native messaging script file shoud be installed to these locations:

Windows

AppData\Local\keepassxc or to the KeePassXC directory if using portable version. Also there should be a registry entry found in the following location(s):

  • Chrome: HKEY_CURRENT_USER\\Software\\Google\\Chrome\\NativeMessagingHosts\\
  • Chromium: HKEY_CURRENT_USER\\Software\\Chromium\\NativeMessagingHosts\\
  • Firefox: HKEY_CURRENT_USER\\Software\\Mozilla\\NativeMessagingHosts\\
  • Vivaldi: HKEY_CURRENT_USER\\Software\\Vivaldi\\NativeMessagingHosts\\
  • Tor Browser: HKEY_CURRENT_USER\\Software\\Mozilla\\NativeMessagingHosts\\
  • Edge: HKEY_CURRENT_USER\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\

The registry entry should only include a (Default) variable and a org.keepassxc.keepassxc_browser subfolder which also has a (Default) variable pointing to the actual JSON script path.

Linux

  • Chrome: ~/.config/google-chrome/NativeMessagingHosts
  • Chromium ~/.config/chromium/NativeMessagingHosts
  • Firefox: ~/.mozilla/native-messaging-hosts
  • Vivaldi: ~/.config/vivaldi/NativeMessagingHosts
  • Tor Browser: ~/.tor-browser/app/Browser/TorBrowser/Data/Browser/.mozilla/native-messaging-hosts
  • Librewolf (Firefox-based) ~/.librewolf/native-messaging-hosts

Tor Browser installed via the official .tar.gz package will look for the following folders (when extracted to the home folder): /home/<user>/tor-browser_en-US/Browser/TorBrowser/Data/Browser/.mozilla/native-messaging-hosts/ and globally from /usr/lib/mozilla/native-messaging-hosts/.

Tor Browser installed via Torbrowser-launcher looks for the following (for en_US): /home/<user>/.local/share/torbrowser/tbb/x86_64/tor-browser_en-US/Browser/TorBrowser/Data/Browser/.mozilla/native-messaging-hosts/

For now, the .json file needed can be symlinked or copied to those directions, for example from under .mozilla/native-messaging-hosts.

macOS

  • Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts
  • Chromium: ~/Library/Application Support/Chromium/NativeMessagingHosts
  • Firefox: ~/Library/Application Support/Mozilla/NativeMessagingHosts
  • Vivaldi: ~/Library/Application Support/Vivaldi/NativeMessagingHosts
  • Tor Browser ~/Library/Application Support/TorBrowser-Data/Browser/Mozilla/NativeMessagingHosts
  • Edge ~/Library/Application Support/Microsoft Edge/NativeMessagingHosts

Brave browser uses the Chrome storage location for native messaging. Choose the Chrome checkbox in KeePassXC Browser integration settings.

If you use any other browser the configuration location can vary. In these cases the script file must be copied manually.

Other browsers

Some example Linux paths:

  • Google Chrome Beta: ~/.config/google-chrome-beta/NativeMessagingHosts
  • Google Canary (Unstable): ~/.config/google-chrome-unstable/NativeMessagingHosts
  • Waterfox: ~/.waterfox/native-messaging-hosts
  • Iridium: ~/.config/iridium/NativeMessagingHosts

2) Check the native messaging script file path and extension ID's

After finding the org.keepassxc.keepassxc_browser.json check the path variable inside it. It should point to the exact location to the KeePassXC binary. In Windows this variable can also exists without a path.

The extension ID under allowed_origins should be chrome-extension://oboonakemofpalcgghocfoadofidjkkk/ for Chromium-based browsers and keepassxc-browser@keepassxc.org under allowed_extensions for Firefox. There can be another ID seen with Chromium. This is the older version of the extension and it will be removed in the future from the script file.

With Chromium-based browsers you can check that the extension ID is the same with what is shown at the extensions page.

3) Check if keepassxc-proxy is launched and running

Connection between KeePassXC and the browser extension is managed by keepassxc-proxy binary. Make sure this is up and running. If not try to start it manually. Under macOS the binary can be found inside the KeePassXC.app at Contents/MacOS/.

If the binary doesn't start on macOS, please check the binary linking with the following command: otool -L /Applications/KeePassXC.app/Contents/MacOS/keepassxc-proxy It should show the following for QtNetwork and QtCore frameworks: @executable_path/../Frameworks/QtNetwork.framework/Versions/5/QtNetwork @executable_path/../Frameworks/QtCore.framework/Versions/5/QtCore

Find the native messaging configuration path with strace

If keepassxc-proxy is not launched and the extension still says it cannot connect, in Linux you can use strace to see where a browser tries to load the script file.

Use the following command: sudo strace -f -p $(pgrep firefox) 2>&1 | grep keepass

With macOS, use opensnoop instead: sudo opensnoop -n firefox-bin | grep org.keepassxc

With Windows you can use Process Monitor.

The go to your browser, open the extension popup and press reload. That should trigger the Native Messaging to open the script file. You should see a line similar to this:

[pid 21992] openat(AT_FDCWD, "/home/varjolintu/.mozilla/native-messaging-hosts/org.keepassxc.keepassxc_browser.json", O_RDONLY <unfinished ...>

Linux: Check Unix domain socket path

The default socket path has been updated in KeePassXC 2.7.4 Updating or downgrading KeePassXC can cause this socket file to point to a wrong location. When using $XDG_RUNTIME_DIR socket file should exists under /run/user/1000/app/org.keepassxc.KeePassXC/org.keepassxc.KeePassXC.BrowserServer and the symbolic link at /run/user/1000/org.keepassxc.KeePassXC.BrowserServer for backwards compatibility should point to this file. If /run/user/1000/org.keepassxc.KeePassXC.BrowserServer is not a symbolic link, the file should be destroyed and let KeePassXC to create it again when restarted.

Linux: Firejail

Filejail also needs permissions for the proxy to run. File ~/.config/firejail/firefox.local should include:

noblacklist ${RUNUSER}/app
mkdir ${RUNUSER}/app/org.keepassxc.KeePassXC
whitelist ${RUNUSER}/app/org.keepassxc.KeePassXC

And file ~/.config/firejail/keepassxc.local:

noblacklist ${RUNUSER}/app

4) Debug the extension itself

If everything else seems to be OK but you still have issues please try to debug the extension.

Chromium-based browsers:

  • Go to the extension page, check Developer mode
  • Click backgroung page link after the Inspect views: text

Firefox:

  • Go to about:debugging and check Enable add-on debugging
  • Find KeePassXC-Browser and click Debug

Console tab should now show any error messages the extension writes. If you are a developer and know these things you can use the Sources tab and debug the extension and find the exact point where it fails.

Debug the content script

For debugging autocomplete, password generator, or anything else that interacts with the web page itself, content scripts must be debugged.

Chromium-based browsers:

  • Use the menu View -> Developer -> Developer Tools or with right mouse click on the page and select Inspect
  • Go to Sources tab and use the double arrow on the top left of the Developer Tools to view Content scripts
  • Open top tree and search for KeePassXC-Browser. Open keepassxc-browser.js

Firefox:

  • Use the menu Tools -> Web Developer -> Debugger
  • Go to Sources tab on the left and search for KeePassXC-Browser. Open keepassxc-browser.js

See another wiki page for video instructions: HowTo: Special situations and debugging

5) Ubuntu Snap

If you are using Ubuntu based distro older than 22.04 Firefox or Chromium installed via Snap will not work. Use the official PPA or AppImage instead.

If there's still an error connecting to the extension, check the container permissions by running: flatpak permissions webextensions. Another command is needed if the permission shows no: flatpak permission-set webextensions org.keepassxc.keepassxc_browser snap.firefox yes. For more detailed info, check this blog post.

6) AppArmor with Ubuntu

If AppArmor is used with Firefox installed from PPA, the following rules must be applied to /etc/apparmor.d/usr.bin.firefox:

# Native Messaging
owner @{HOME}/.mozilla/**/native-messaging-hosts/** ixr,
/usr/bin/keepassxc-proxy ixr,
/run/user/1000/org.keepassxc.KeePassXC.BrowserServer ixr,
/run/user/1000/app/org.keepassxc.KeePassXC/org.keepassxc.KeePassXC.BrowserServer wr,

After adding the rules, restart the profile using sudo aa-enforce /etc/apparmor.d/usr.bin/firefox.

7) Windows-specific with Chromium based browsers (Chrome, Edge, Vivaldi, Brave etc..)

In some cases nothing of the above works, and keepassxc-proxy.exe still doesn't start. If so, please check if you have ComSpec environment variable unset. That should point to cmd.exe.

Enviroment variables can be checked by running rundll32 sysdm.cpl,EditEnvironmentVariables from Command Prompt as administrator. Alternatively it's found from Control Panel > System and Security > System > Advanced system settings > Advanced > Environment Variables. ComSpec should usually point to C:\WINDOWS\system32\cmd.exe, but it should be adjusted for your system. After applying the enviroment variable, logout/login or restarting the system is needed.

Group policy changes

Workspace computers might have NativeMessagingUserLevelHosts disabled. In this case Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\NativeMessagingUserLevelHosts is set to zero. Active policies can be checked via edge://policy.

Clone this wiki locally