Complete the getting started tutorial first if you can.
Pay special attention to any troubleshooting advice displayed at the top of the page. For some problems, this can at least give you a clue about the type of problem that is preventing Kee from behaving the way you expect.
Once the basics are working, going through the contents of the tutorial will ensure you’re up-to-date with the basic features of Kee.
If the tutorial does not work for you or does not answer your specific question, the troubleshooting tips below may help.
If you have just upgraded from KeeFox 1.x, you should review the extra detail on the Kee 2.0 features page.
- Kee icon displays an OFF label
- I have to enter a password every time I load Kee
- KeePassRPC is already listening for connections
- A particular website does not get its login form filled in automatically
- The Kee icon in the username/password field is missing or inaccessible
- KeePass tells me that the plugin could not be loaded
- View logs / debug the problem
- My problem/question is not listed here
Kee icon displays an OFF label
If it is orange, you need to log in to or unlock your password database.
If it is red, this indicates that Kee has not been able to connect to your password manager. The most common reason for this is that the password manager is not running - to resolve that, ensure that KeePass is running on your computer.
If KeePass is running and you have correctly followed the installation or upgrade instructions, there could be other problems preventing communication between your web browser and KeePass. Some common things to look at include:
- Other security software such as anti-virus or firewall (Kee communicates on TCP port 12546 by default).
- Sophos Anti-virus is an example of a consistently badly behaved piece of software in this regard.
- Try white-listing 127.0.0.1 and localhost in your security software settings (ask them for help if you’re not sure how to do this).
- Other web browser add-ons/extensions, KeePass plugins or ad blockers. A small list of examples that were known to cause problems with KeeFox and may still be problematic for Kee 2.0:
- RequestPolicy - This CSRF protection add-on has a bug that causes it to think that the connection from Kee to KeePass is a cross-site request that should be blocked. Until the RequestPolicy devs resolve the problem, it’s easy to workaround by adding a rule to always allow traffic to 127.0.0.1:12546
- FoxyProxy (and maybe other proxy add-ons) - When this addon is configured to proxy all web browser traffic through a specific proxy server, Kee connections to KeePass will also be affected. It should be possible to configure FoxyProxy rules to avoid this but that’s beyond the scope of this manual. Alternatively, other proxy add-ons may allow all remote traffic to go through a remote proxy while leaving the local traffic untouched.
- Ad Muncher - This system-wide ad blocker has a bug that breaks web sockets on your system (increasingly, you will find more websites and applications fail while using this software).
- KeePassHTTP - No verified problems in Kee yet but there were some issues with earlier versions. Since Kee can now work in Chrome, there should be a limited need to run both this and KeePassRPC concurrently so it’s at least worth removing this for a trial period.
- Privacy Badger - May get a false positive from Kee and block 127.0.0.1 after a while. Can be fixed by going to privacy badger settings and manually setting 127.0.0.1 to Allowed.
- Is your web browser configured to use a proxy? Make sure that it is not sending local network traffic to the remote proxy. For example, the Windows proxy settings have an option to “Bypass proxy server for local addresses” - make sure that option is enabled.
- You may have configured a custom port at some point in the past and need to repair your configuration. See KPRPC Port for information on how it should be configured. This may be because you do (or have previously) run more than one instance of KeePass or have other people that share your computer with KeePass open at the same time.
- Make sure that you have exactly one KeePassRPC.plgx file in your KeePass program folder. Kee installation instructions put the plugin into a subfolder called “Plugins” but KeePass will load any plugin it finds in its own folder too. So if you have manually tweaked the KeePass program folder or made a backup of the plgx file you might have more than one KeePassRPC plugin installed, possibly an older version.
- Check if your network hosts file is correctly configured to send localhost traffic to your local 127.0.0.1 IP address
- If you’re still stuck and want to gather some more information to help you or someone else diagnose the problem, you could try running this JSFiddle to test if your web browser is able to connect to KeePass: http://jsfiddle.net/awDLc/125/
When testing, be aware that some applications / add-ons will only prevent the initial connection from Kee to KeePass. For example, forcing all localhost traffic through an external proxy using a tool like FoxyProxy will not cause any problem provided that you have already established a connection between your web browser and KeePass (until you close one of those applications). This could be a useful way to work around some problems until third parties resolve the problem at their end, but it could also lead to confusing results if you’re not careful when trying to narrow down the cause of your connection problem!
If nothing above helps, please try to debug the problem with the aid of the instructions below and the community on this forum.
I have to enter a password every time I load Kee
Naturally, there are a lot of passwords involved with a password manager so first let’s be clear what password you’re being asked to enter.
This type of password should appear if you’re installing Kee for the first time, it’s been a long time since you first installed it or you have just upgraded from KeeFox. You’ll be asked to type a random password from a KeePass dialog box into one displayed by your web browser.
If you keep being asked to enter this random password it could be caused by any of the following:
- You have set Kee (and KeePassRPC) to the high security level
- You have set a very short expiry time for the authorisation
- You have some other add-on or setting which prevents your web browser from saving the Kee authorisation key.
- Maybe some other reasons we’ve not come across yet (such as problems with your web browser or KeePass being unable to save their configuration files?)
Other password dialogs
It’s probably unnecessary to mention the KeePass master key dialog but let’s cover it for completeness. This dialog is presented by the KeePass password manager, you would have it even without the Kee addon installed and it is the main password you need to enter in order to access all the other passwords stored within your KeePass database. There are KeePass options you can set to adjust how frequently you need to enter this password but that’s beyond the scope of this manual - check out the support resources at http://keepass.info for more information.
If you’re asked for any other passwords, they will be from websites you visit or other browser add-ons. Look for any websites that are set to load every time you start your web browser and try disabling other add-ons/extensions if you can’t pin down the cause.
KeePassRPC is already listening for connections
If you see this error message when you start KeePass, Kee will be unable to connect to KeePass to access your passwords.
These are the most likely explanations in decreasing order of likelihood:
You already have a version of KeePass running.
Someone else logged into your computer and already has a version of KeePass running.
A different application on your machine is using one of the ports KeePassRPC requires (12536 and 12546)
Plugin files required by Kee aren’t properly installed. Before you try to run KeePass again, verify that you have copied
KeePassRPC.plgxinto a subfolder named
Pluginswhich you have placed inside the KeePass application directory. Note for Linux/Mac users: Ensure the
Pluginssubfolder starts with a capital P.
For example: if your KeePass application directory is named
/home/bob/KeePass, then put
KeePassRPC.plgxinto a subfolder named
/home/bob/KeePass/Plugins/(note the capital P). For the list of common locations for the KeePass application directory, visit their configuration files help page.
To help diagnose the cause of the error, you may want to use the Windows 7 resource monitor tool’s “network” tab or equivalent monitoring tools on your operating system.
If you need to run more than one instance of KeePass (such as for multiple users on the same machine), you’ll need to configure each pair of KeePass and web browser to use a different port.
A particular website does not get its login form filled in automatically
- Check that your KeePass entry is configured correctly. If in doubt, it is often easiest to log in to the site manually and get Kee to update the password or even save the password as a new entry.
- If you can’t get the automatic behaviour to work, you can always use the “copy username/password” feature available on each matched login.
- If all else fails, you should learn how to use the KeePass auto-type feature. This simulates the typing of keys on your keyboard so with appropriate use of tabs, spaces and other characters you may be able to submit a login through that method.
Please do let us know on the forum when you find sites that don’t work. We’ll definitely take a look into it and see if we can improve Kee in the future so that it works with even more sites. Unfortunately, we may not always be able to respond to each individual report.
The Kee icon in the username/password field is missing or inaccessible
Occasionally a web site will be created in a way that means the Kee icon is either hidden entirely or displayed underneath another icon or button. If that happens and it is difficult to click on the Kee icon, don’t forget that you can tell Kee to auto-fill a form using the “Matched login entries” button in the Kee main menu in your browser toolbar. You can also use the keyboard shortcut Ctrl-Shift-2 (this may be different on Apple Macs)
If the icon and the “Matched login entries” button is missing, it could be because Kee has not detected that this is a sign-in form - advice on how to resolve that problem in most cases are elsewhere in this topic and community forum.
KeePass tells me that the plugin could not be loaded
When the KeePassRPC plugin does not get loaded correctly, the error message displayed in KeePass (for English users) will typically be similar to “The following plugin is incompatible with the current KeePass version”.
There can be a variety of reasons for this, most of which will require you to upgrade (or sometimes downgrade) one or more of the components on your system.
There are no known reasons for this problem if you are using the latest version of KeePassRPC and KeePass on Windows 7 or newer.
If you do suffer from the problem and updating to the latest version of KeePass and KeePassRPC does not resolve the problem, it is probably due to a corruption in your Windows installation (sometimes specifically the Microsoft .NET windows component) so repairing Windows and/or reinstalling the .NET Framework might help. These problems are sometimes caused by malware so make sure you thoroughly test for and eradicate any viruses, spyware, etc.
Linux and Mac users
There are dozens of bugs that affect Mono and KeePass on these platforms. In general you just need to install the latest versions of KeePass, KeePassRPC and Mono although Mono has in the past created new problems when it fixes old ones so sometimes this won’t be enough.
Note that your distro’s package manager (e.g. apt-get for Ubuntu/Debian) may not hold the most relevant versions so depending on your exact Linux or Mac version, you might find that a full package upgrade is not sufficient to make the KeePassRPC plugin work.
The most common problem appears to be that the default installation of Mono does not include all required components to support KeePass plugins. The easiest way to resolve this is to ensure that the mono-complete package is installed.
Note that on some Debian-based Linux distributions, installing the keepass2 package does NOT install mono-complete.
If that doesn’t help, try different versions of Mono and make sure you have read any other information on this forum about running Kee on Linux/Mac/Mono.
View logs / debug the problem
If the above tips don’t help, you can enable some extra logging which can help you to work out what is causing the problem and, depending on your level of technical knowledge, either provide more information when asking for help from the community or guide you to developing a solution yourself.
Each of the components relating to the Kee browser extension has their own logging system.
The Kee browser extension itself
Set the log level using the Kee Options (e.g. from the button in the Kee main menu). By default this will log all events that are either errors or warnings but you can increase this to include extra information or debug events too.
The logs themselves are added to the relevant console. It’s not practical to understand exactly where each event will be logged to so in general it makes sense to check both locations but as a rule of thumb, for issues relating to the way Kee interacts with the web page, look at the “Web console” and for issues relating to the link to your password manager, look at the “Browser console”. Those are the terms that Firefox uses but there are similar concepts in other browsers.
Debugging other areas like the Kee Options page or the Kee main menu panel can also be done and some logs will be created in the consoles that relate to those areas. However, that is a more complex task that varies a lot based upon which browser you are using and is therefore beyond the scope of this guide.
You can view the Kee Vault logs by clicking on the Settings icon; then click on the “Show app logs” button at the bottom. It also logs the same information to the “Web Console”.
Run KeePass from the command line / terminal with some extra parameters to enable some debug logging which may be useful to diagnose connection problems.
The following are the most useful:
--debug : This puts KeePass into debug mode. Depending on what went wrong, KeePass will tell you where to find a file with debug output, provide useful information in a popup or just output a generic and meaningless message.
--KPRPCDebug= : Output KeePassRPC plugin debug information to a location of your choosing. E.g.:
On Windows, you can launch KeePass using these options by following these steps:
- Ensure all instances of KeePass are closed (and not running in the system tray)
- Open a command prompt (through the start menu or use your keyboard - WinKey+R and then type
- Enter this command:
KeePass.exe --debug --KPRPCDebug=c:\temp\kprpc-debug.log
a. You may need to create the
tempfolder first or pick a different location for the log file to be written to
My problem is not listed here
The next step should be to search and ask for help on the community forum.