Troubleshooting¶

Quick Fixes¶

Try these first.

Force Quit¶

If StormTunnel is frozen:

1. Press Cmd+Option+Esc
2. Select "StormTunnel"
3. Click "Force Quit"
4. Relaunch from Applications

Clear Known Hosts¶

If you see "Host key verification failed":

1. Quit StormTunnel
2. Delete ~/Library/Application Support/StormTunnel/SSH/known_hosts
3. Relaunch and reconnect (verify the new host key)

Reset StormTunnel¶

1. Quit StormTunnel
2. Delete ~/Library/Containers/in.rs.olujic.StormTunnel/
3. Relaunch and reconfigure

Error Reference¶

Look up the error message you see:

Connection Issues¶

Tunnel Won't Connect¶

Connection Timeout¶

1. Increase timeout: Settings > General > Connection Timeout
2. Check network: Try wired instead of WiFi
3. Check firewall: Verify SSH port is not blocked

Connection Drops¶

1. Enable auto-reconnect: Edit tunnel > Advanced > Auto-Reconnect
2. Check network stability: WiFi interference, cable issues
3. Prevent Mac sleep: Adjust Energy Saver settings

Authentication Problems¶

"Permission denied (publickey)"¶

Your SSH key is not authorized on the server.

1. Verify correct key is selected in tunnel settings
2. Ask admin to add your public key to the server's ~/.ssh/authorized_keys
3. Test manually: ssh -i /path/to/key user@host
4. Try CLI fallback: Edit tunnel > Advanced > Use CLI Fallback

"Authentication failed" (Password)¶

1. Verify password is correct (check Caps Lock)
2. Re-enter password in tunnel settings
3. Ask admin if password changed
4. Try CLI fallback mode

Two-Factor Authentication¶

StormTunnel's native SSH does not support interactive 2FA prompts.

Workaround: Enable CLI Fallback mode:

1. Edit tunnel > Advanced > Use CLI Fallback
2. Connect -- you will see the 2FA prompt
3. Enter your code when prompted

Port Issues¶

"Port already in use"¶

Another application is using that local port.

1. Choose a different local port (e.g., 5433 instead of 5432)
2. Find what is using the port: lsof -i :PORT
3. Close the conflicting application

"Port forwarding failed"¶

1. Verify remote host and port are correct
2. Check if the service is running on the remote server
3. Ask admin to verify the firewall allows the connection

AWS Session Manager Issues¶

"Session Manager plugin not found"¶

AWS CLI plugin is not installed or not in PATH.

1. Install plugin: brew install --cask session-manager-plugin
2. Verify in Settings > AWS > Plugin Status
3. If custom location, set path in Settings > Advanced

"Access Denied" or IAM errors¶

1. Check AWS profile is configured: Settings > AWS
2. Verify IAM permissions with your AWS admin
3. Test AWS CLI: aws sts get-caller-identity

Required IAM Permissions¶

Your AWS admin needs to grant:

• ssm:StartSession
• ssm:TerminateSession
• ec2:DescribeInstances (for instance list)

See AWS IAM Policies for full policy examples.

UI Issues¶

Application Won't Launch¶

1. Check macOS version: Requires macOS 15.0+
2. Check security: System Settings > Privacy > Allow StormTunnel
3. Reset app: Delete ~/Library/Containers/in.rs.olujic.StormTunnel/ and relaunch

Interface Frozen¶

1. Force quit: Cmd+Option+Esc > Select StormTunnel > Force Quit
2. Restart: Reopen from Applications
3. Check resources: Close other apps if memory is low

Menu Bar Icon Missing¶

1. Enable: Settings > General > Show in Menu Bar
2. Check menu bar space (remove other icons if full)
3. Restart StormTunnel

Performance Issues¶

Slow Connections¶

1. Use IP address instead of hostname (avoids DNS lookup)
2. Increase connection timeout
3. Check network latency

High CPU/Memory¶

1. Disconnect unused tunnels
2. Restart StormTunnel
3. Check Activity Monitor for other resource-heavy apps

Connection History Issues¶

History Not Showing¶

1. Check privacy settings: Settings > Privacy > Connection History
2. Verify tunnel is tracked (some tunnels can be excluded)
3. Check license: Free tier limited to last 5 entries
4. Restart StormTunnel

Missing Events¶

Statistics Incorrect¶

1. Verify date range: check the time period you are viewing
2. Check for orphaned events: restart app to trigger cleanup
3. Check filter settings: make sure filters are not hiding events
4. Refresh view: Cmd+R

Performance with Large History¶

1. Reduce retention: Settings > Privacy > History Retention Days
2. Limit per tunnel: Settings > Privacy > Max Events Per Tunnel
3. Clear old history
4. Exclude frequently-changing tunnels from tracking

Search Issues¶

Search Not Finding Tunnels¶

Search Performance¶

If search is slow:

1. Archive old tunnels you no longer use
2. Close other apps if memory is low
3. Restart StormTunnel

Retry & Reliability Issues¶

Retry Not Working¶

Too Many Retry Attempts¶

1. Lower retry count: Edit tunnel > Advanced > Max Retry Attempts
2. Fix root cause: network issue, wrong credentials, server down
3. Check logs: Connection History shows retry attempts
4. Disable retry temporarily while debugging

Retry Exhausted Errors¶

When to Disable Retry¶

Retry with Different Auth Methods¶

1. Try CLI fallback: Edit tunnel > Advanced > Use CLI Fallback
2. Check SSH key: verify key is in Settings > Keys
3. Test password auth: temporarily switch to password method
4. Update credentials: refresh password or key if expired

Getting Help¶

Enable Debug Logging¶

1. Settings > Advanced > Enable Debug Mode
2. Enable Verbose SSH Output (for SSH issues)
3. Reproduce the problem
4. Check Console.app, filter by "StormTunnel"

Report an Issue¶

Include:

• StormTunnel version (Settings > About)
• macOS version
• Steps to reproduce
• Error messages
• Debug logs if available

Contact: support@storm-tunnel.app