Troubleshooting Viscosity Problems (Mac)
In rare instances Viscosity, or one of its components, may encounter a problem that prevents it from being able to function correctly under macOS. Below you can find some solutions to the more common issues you might face.
For general VPN connection troubleshooting please instead refer to the Troubleshooting Connection Problems article.
Viscosity Does Not Start
If you launch Viscosity and it doesn't appear to start, or it quits immediately, then there is likely a software incompatibility on the computer.
The first step is to ensure that Viscosity is up-to-date. Older versions of Viscosity may not be compatible with newer versions of macOS, and may crash or hang when launched. Please refer to Installing Viscosity (Mac) for how to check that the latest version is installed.
It is also important to try restarting your computer. This is an important step, as it ensures any stuck processes in the background are cleared. If Viscosity, or its helper tool, is stuck in the background, attempting to re-open Viscosity may have no effect.
In some instances third-party AntiVirus or enterprise security software may prevent Viscosity from launching or cause it to crash. If any such software is installed, it should be temporarily disabled and/or uninstalled, and then Viscosity checked to see whether it can launch.
If this is a workplace or company managed computer, then your IT staff should also be contacted to see whether any enterprise security/management software (such as "SentinelOne" or "Digital Guardian") could be preventing Viscosity from launching or interfering with its operation. In some cases Viscosity may need to be white-listed.
If Viscosity is still unable to launch, completely uninstalling Viscosity, restarting, and then reinstalling Viscosity may resolve the issue. Please backup any important connections or settings before uninstalling Viscosity.
Viscosity Does Not Start at Login
In some instances the "Start Viscosity at Login" option may be enabled, however Viscosity does not appear to open at login. Or it may open but the Viscosity icon or menu is unresponsive. In these cases, force-quitting Viscosity using Activity Monitor and then manually re-opening it, will typically allow it to start.
This is caused by macOS attempting to launch an old version of Viscosity (that is incompatible with the version of macOS it is running on) that is also present on the computer. Old versions of Viscosity will typically crash or hang when launched on newer versions of macOS.
When macOS launches a Login Item, it will search for the corresponding application by its bundle ID (rather than by a fixed location) and launching the first match it finds. If more than one copy of the Viscosity application is present this can result in the wrong copy being launched at login. For example, the latest copy of Viscosity may be installed in your computer's Applications folder, however macOS could be finding an old copy in your Downloads folder and launching that instead. If this version is too old to run on your version of macOS, it will make it seem like Viscosity always crashes/hangs at login.
Occasionally an old copy can be found in an unexpected location, for example left behind by the Sparkle updater in ~/Library/Caches/ if a past update attempt failed, or on an external network volume.
The simplest way to resolve this is to delete any old versions of Viscosity from your computer, and to ensure your primary version of Viscosity is up to date. Please see the steps below.
Step 1: Ensure That Viscosity is up to Date
Before proceeding any further it's recommended that you ensure that the latest version of Viscosity is installed. Please refer to Installing Viscosity (Mac) for how to check that the latest version is installed.
Step 2: Search for Old Copies by Bundle ID
macOS's "mdfind" tool can be used to find any additional copies of Viscosity installed like so:
- Ensure that any disks and external drives that are normally connected at login are connected.
- Open the Terminal application, located in the /Applications/Utilities/ folder.
- Enter the command
mdfind kMDItemCFBundleIdentifier = "com.viscosityvpn.Viscosity"and press Return/Enter on your keyboard.
- A list of matches should appear. For example, the following shows that a copy of Viscosity was found in both the Applications folder as well as the user's download folder:
mdfind kMDItemCFBundleIdentifier = "com.viscosityvpn.Viscosity"
- Go to the paths indicated for any additional copies of Viscosity and delete them. Be sure to empty the Trash.
Step 3: Search for Old Copies Using Spotlight
In some instances it is also worth searching for any additional copies of Viscosity using Spotlight:
- Click on the Spotlight icon in the top right of the menu bar.
- Enter "Viscosity" (without the quotes) and wait a few seconds for results to appear (don't press Return/Enter, as this may launch Viscosity).
- For any additional copies found, locate them and delete them. Be sure to empty the Trash.
Step 4: Remove the old Login Item
Before restarting it is a good idea to also remove the old Viscosity Login item. Once done, restart your computer, and then re-enable Viscosity's "Start Viscosity at Login" option. For information on how to remove the Login Item please refer to this Apple support document.
If the issue still occurs after following the above steps, please refer to the "Viscosity Does Not Start" section above.