Skip to content

Troubleshooting guide

Jump to bottom
Sami Vänttinen edited this page Sep 9, 2024 · 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.

Basic understanding: What's happening under the hood?

This is explained for Firefox on Linux but it's very similar for other setups.

  1. If you enable browser integration for Firefox in KeepassXC (Application Settings -> Browser Integration -> [x] Firefox -> OK), KeepassXC writes a small config file to ~/.mozilla/native-messaging-hosts/org.keepassxc.keepassxc_browser.json. This config file contains the location of keepassxc-proxy (for example/usr/bin/keepassxc-proxy)
  2. If you start Firefox it reads the json file. This explains why, in some cases, a restart of Firefox is necessary. The technology used here is called native messaging (here you can find a small but complete example). If the KeepassXC browser extension sends a native message (like it happens if you press 'Connect to database'), Firefox executes keepassxc-proxy and keeps it open. Firefox uses stdin/stdout of keepassxc-proxy for communication. So basically, Firefox just keeps stdin/stdout open for the whole time and sends/receives data to keepassxc-proxy.
  3. The communication between keepassxc-proxy and KeepassXC uses a unix domain socket (/run/user/1000/app/org.keepassxc.KeePassXC/org.keepassxc.KeePassXC.BrowserServer), which is provided by KeepassXC.

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". Please note that in general Flatpak and Snap based browsers are not supported, Ubuntu's Firefox Snap being an exception. 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 have an org.keepassxc.keepassxc_browser subfolder which 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
  • Arc: ~/Library/Application Support/Arc/User Data/NativeMessagingHosts

Brave and Arc browsers can use the Chrome storage location for native messaging. Choose the Chrome checkbox in KeePassXC Browser integration settings.

In KeePasSXC's settings, Browser Integration's Advanced tab allows to set a single Custom Browser manually. When enabling that option with a path (possibly one of the above) will copy the manifest file to that location. If you use any other browser the configuration location can vary.

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.

  • Chromium-based Browsers, under allowed_origins:
    • chrome-extension://oboonakemofpalcgghocfoadofidjkkk/ for the Chrome Store extension
    • chrome-extension://pdffhmdngciaglkoonimfcmckehcpafo/ for the Edge store extension
  • Firefox-based Browsers, under allowed_extensions:
    • keepassxc-browser@keepassxc.org

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. If there is no keepassxc-proxy process and you are using Snap, check the section below. 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 ...>

You can also inspect the communication between Firefox and keepassxc-proxy (in this case KeepassXC is not running, so there is no response to the change-public-keys request)

vagrant@jammy64-desktop:~$ ps aux | grep keepassxc-proxy
vagrant     6560  0.0  0.5 129724 10148 ?        Sl   18:20   0:00 /usr/bin/keepassxc-proxy

vagrant@jammy64-desktop:~$ sudo strace -f -yy -e read,write -s 1000000 -p 6560
strace: Process 6560 attached with 2 threads
[pid  6564] read(0<pipe:[67486]>, "\263\0\0\0{\"action\":\"change-public-keys\",\"publicKey\":\"m1LLw1QtVNd+9F//r0tm+y7+BMhb0s+k8QAM9eysgnM=\",\"nonce\":\"E4EBHcQ97S7daz0yJHMk+M7Cf7rIDVfn\",\"clientID\":\"Hx6X0b0/D2pnJb3qoNRqX2PshmKgoCQC\"}", 4096) = 183
[pid  6564] write(3<anon_inode:[eventfd]>, "\1\0\0\0\0\0\0\0", 8) = 8
[pid  6560] read(3<anon_inode:[eventfd]>, "\1\0\0\0\0\0\0\0", 16) = 8
[pid  6564] read(0<pipe:[67486]>,

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. Maybe flatpak needs to be installed before (apt-get install -y flatpak). Another command is needed if the permission shows no: flatpak permission-set webextensions org.keepassxc.keepassxc_browser snap.firefox yes. To verify correct permissions, use

vagrant@jammy64-desktop:~$ flatpak permissions
Table         Object                          App          Permissions Data
webextensions org.keepassxc.keepassxc_browser snap.firefox yes         0x00

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.

To make sure if AppArmor is blocking the proxy, the following command can be used to identify the problem:

sudo journalctl -t audit | grep 'apparmor="DENIED"' | grep "$(which keepassxc-proxy)"

The output should show DENIED messages from AppArmor if the extra rules above are needed.

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.

Configure the registry using these values.

Clone this wiki locally