Skip to content

Troubleshooting

Start with the tunnel type and exact error message. For AWS tunnels, check the AWS profile, session permission and managed instance, path from EC2 to the destination, and local port in that order. Validate and Test Permissions are preflight checks; neither starts the port forward or tests the database network path.

AWS Session Manager Issues

AWS CLI or Plugin Not Found

StormTunnel needs AWS CLI v2 and the Session Manager plugin on your Mac. In the tunnel editor, AWS Tools Missing appears under Check Access when either is not found.

  1. Install or update both components (for example brew install awscli session-manager-plugin).
  2. Open Settings > AWS, click Verify AWS Setup…, and confirm both show as ready. StormTunnel searches /opt/homebrew/bin and /usr/local/bin, plus the AWS plugin installer location.
  3. Run aws --version in Terminal and confirm it reports version 2. Validate and Test Permissions require AWS CLI v2 because they resolve credentials with aws configure export-credentials.

See AWS configuration.

Access Denied or Expired Credentials

  1. Confirm the selected profile and region.
  2. Click Validate under Check Access. If the message mentions an expired SSO session, MFA, or a missing AWS CLI, fix that first. For an IAM Identity Center profile, sign in again with aws sso login --profile PROFILE, or use Sign In Again… with a Premium license.
  3. Click Test Permissions. Describe permissions marked Missing can be granted by your AWS administrator. ssm:StartSession and ssm:TerminateSession always show Unverified because the check does not start or end a session. If preflight succeeds but connecting the tunnel returns AccessDenied, ask your administrator to check the session-start permission and access to the port-forwarding document.
  4. Ask your AWS administrator to check permission to start the port-forwarding session, use its SSM document, and end your sessions. Copy IAM Policy copies an example.
  5. Check for permission boundaries or organization policies that may deny access.

See AWS IAM permissions.

Instance Not Found or Offline

Confirm the instance ID and region. The EC2 instance must be online as a Systems Manager managed node and have permission to communicate with Systems Manager.

See AWS configuration.

Connection Refused or Timed Out

The connection from the EC2 instance to the destination may be blocked. Check that:

  • The remote host and port are correct.
  • The instance can resolve the host and reach the port.
  • VPC routes and network ACLs allow the connection.
  • The destination security group allows traffic from the EC2 instance's security group.

For RDS, see Connect to a private AWS RDS database.

Local Port Already in Use

Choose another local port. If you need to identify the process using the port, run:

lsof -i :5432

SSH Tunnel Issues

Permission Denied (Public Key)

Confirm that the selected key is authorized on the server. Ask the server administrator to add the matching public key to ~/.ssh/authorized_keys.

Host Key Verification Failed

Confirm the server identity with its administrator before accepting a changed host key. Manage saved host keys in Settings > Known Hosts.

SSH Connection Times Out

Check the host, SSH port, network connection, VPN, and server availability. Ask the administrator whether a firewall blocks the connection.

Application Issues

Tunnel Does Not Start

  • Confirm the required fields and ports are valid.
  • Check whether the local port is already in use.
  • Select the tunnel to read its error, or click Details… next to a failed Validate for the full message.
  • If the issue continues, contact support with the tunnel type and error text. Do not include credentials, private keys, or session tokens.

Open Settings > General and turn on Show Status in Menu Bar. If the menu bar is crowded, check whether macOS has hidden the icon.

Recent Errors

Choose Window → Error Analytics to see recent errors recorded since StormTunnel started. See Error analytics.

More Help