-
-
Notifications
You must be signed in to change notification settings - Fork 183
Troubleshooting guide
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.
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:
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.
- 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
.
- 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.
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
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
[email protected]
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.
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
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 ...>
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.
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
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 theInspect views:
text
Firefox:
- Go to
about:debugging
and checkEnable 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.
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 selectInspect
- Go to
Sources
tab and use the double arrow on the top left of the Developer Tools to viewContent scripts
- Open
top
tree and search forKeePassXC-Browser
. Openkeepassxc-browser.js
Firefox:
- Use the menu
Tools -> Web Developer -> Debugger
- Go to
Sources
tab on the left and search forKeePassXC-Browser
. Openkeepassxc-browser.js
See another wiki page for video instructions: https://github.com/keepassxreboot/keepassxc-browser/wiki/HowTo:-Special-situations-and-debugging
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.
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.
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
.