-
-
Notifications
You must be signed in to change notification settings - Fork 176
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.
This is explained for Firefox on Linux but it's very similar for other setups.
- 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
) - 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.
- 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.
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:
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.
- 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
- 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.
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.
- 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.
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
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]>,
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: 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
. 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.
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.
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
.
Configure the registry using these values.