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.

Before troubleshooting the issue further, please be aware that Viscosity does not appear in the Dock. Viscosity's icon not appearing in the Dock, or (if manually added to the Dock) appearing without a running indicator, does not indicate that Viscosity failed to start. Instead Viscosity displays an icon in your menu bar (on the right hand side near the clock) while running. For more information please see Getting Started With Viscosity (Mac).

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 on macOS 12 (Monterey)

Viscosity version 1.10.1 (or later) is required for macOS 12. Earlier versions of Viscosity are not compatible with macOS 12 and may fail to start. If Viscosity is not starting, please ensure that you're using the latest version, which can be downloaded from the Viscosity Download page.

Viscosity's Icon Does Not Appear on MacBooks With a Notch

If you're using an Apple Silicon MacBook with the "notch" in the screen, please ensure that there is adequate empty space to the right hand side of the menu bar for Viscosity’s menu icon to appear. If you have a lot of menu icons macOS may be placing Viscosity's menu icon behind the notch, in which case please temporarily remove some menu icons to free up space and move Viscosity’s icon to the right.

You can move Viscosity's icon by holding down the Command (⌘) key on your keyboard, and click-and-dragging Viscosity's icon to the desired position.

Helper tool permissions are incorrect. Please try reinstalling.

Before connecting a VPN connection, Viscosity performs a check on its internal tools to ensure they're valid. If a VPN connection fails to connect with the message "Helper tool permissions are incorrect. Please try reinstalling." in the connection log, it indicates that there is a problem with the installation of the helper tools.

The most common cause for this failure is a corrupt copy of Viscosity causing the tool upgrade to fail. The Viscosity application bundle can be corrupted if it is copied incorrectly, causing the bundle to be inadvertently modified (thereby breaking the code signature on the application). If using a script to deploy Viscosity, please ensure the correct commands are being used to copy it into place. For example, use "cp -R" instead of "cp -r" as the copy command, as the latter will break internal symlinks.

The Viscosity application can also be corrupted by third-party software that may attempt to modify it. Make sure any third-party software, such as security or enterprise management software, is not modifying the Viscosity application bundle or blocking the update of its helper tools.

This issue can be resolved by quitting any running copies of Viscosity, downloading the latest version of Viscosity, and then copying the Viscosity application into the Applications folder by clicking and dragging it. If the issue still persists, ensure that any old copy of Viscosity's helper tools are uninstalled.

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:

1. Ensure that any disks and external drives that are normally connected at login are connected.
2. Open the Terminal application, located in the /Applications/Utilities/ folder.
3. Enter the command mdfind kMDItemCFBundleIdentifier = "com.viscosityvpn.Viscosity" and press Return/Enter on your keyboard.
4. 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"
   /Applications/Viscosity.app
   /Users/username/Downloads/Viscosity.app

5. 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:

1. Click on the Spotlight icon in the top right of the menu bar.
2. Enter "Viscosity" (without the quotes) and wait a few seconds for results to appear (don't press Return/Enter, as this may launch Viscosity).
3. 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.