Skip to content

Troubleshooting

Jump to bottom
James Wragg edited this page Feb 28, 2026 · 1 revision

Here are some basic troubleshooting tips.

OTP prompt appears but nothing is submitted

The connection name doesn't match. The name in your defaults write command must match the Viscosity connection name exactly, including case and spacing.

Check what's configured:

defaults read net.skycmd.viscosity-otp

Compare with the connection name shown in Viscosity's menu bar or preferences.

Error dialog: "No OTP command configured for '...'"

No command has been mapped for this connection. Add one:

defaults write net.skycmd.viscosity-otp "<connection-name>" "<otp-command>"

See Configuration for details.

Error dialog: "OTP command failed: ..."

The configured shell command returned a non-zero exit code. The error message shown is the command's stderr output.

Test the command directly:

defaults read net.skycmd.viscosity-otp "<connection-name>" | sh

Common causes:

  • The CLI tool isn't installed or isn't at the expected path
  • You're not signed in to your password manager
  • The item UUID or name is incorrect
  • The CLI tool needs an unlocked session (e.g. Bitwarden)

Error dialog: "Connection name not set"

The script is being run outside of Viscosity. BeforeConnect.applescript relies on the $displayName environment variable that Viscosity sets when calling Before Connect scripts. It cannot be run standalone.

Script changes aren't taking effect

Viscosity caches Before Connect scripts. After updating BeforeConnect.applescript:

  1. Open Viscosity → Preferences
  2. Edit the connection
  3. Under Advanced, clear the Before Connect Script
  4. Save
  5. Edit again and re-select the updated script
  6. Save

macOS permission prompt on every connection

This is the TCC SystemPolicyAppData prompt. See Known Limitations for details and workarounds.

1Password Touch ID times out

Viscosity gives Before Connect scripts approximately 10 seconds to complete. If the 1Password Touch ID prompt appears and you don't approve it quickly enough, Viscosity may terminate the script.

Solution: Approve the Touch ID prompt promptly when it appears.

Command works in Terminal but fails in Viscosity

The shell environment inside do shell script (which Viscosity uses to run AppleScript) is minimal — it does not load your .zshrc, .bashrc, or .bash_profile.

Solution: Use absolute paths for all commands in your OTP command:

# Bad
defaults write net.skycmd.viscosity-otp "My VPN" "op item get abc123 --otp"

# Good
defaults write net.skycmd.viscosity-otp "My VPN" "/usr/local/bin/op item get abc123 --otp"

To find the absolute path of a command:

which op

Clone this wiki locally