Troubleshooting¶

Solutions for common StormTunnel issues.

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 isn't 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 isn't authorized on the server.

Solutions:

1. Verify correct key is selected in tunnel settings
2. Ask admin to add your public key to 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 doesn't support interactive 2FA prompts.

Solution: Enable CLI Fallback mode:

1. Edit tunnel → Advanced → Use CLI Fallback
2. Connect - you'll see 2FA prompt
3. Enter your code when prompted

Port Issues¶

"Port already in use"¶

Another application is using that local port.

Solutions:

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

"Port forwarding failed"¶

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

AWS Session Manager Issues¶

"Session Manager plugin not found"¶

AWS CLI plugin isn't installed or not in PATH.

Solutions:

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 periodically
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: Sometimes history needs refresh

Missing Events¶

If connection events aren't being recorded:

Statistics Incorrect¶

If numbers don't match expected values:

1. Verify date range: Check if you're looking at the right time period
2. Check for orphaned events: Restart app to trigger cleanup
3. Filter settings: Make sure filters aren't hiding events
4. Refresh view: Use Cmd+R to reload statistics

Performance with Large History¶

If StormTunnel is slow with many events:

1. Reduce retention: Settings → Privacy → History Retention Days
2. Limit per tunnel: Settings → Privacy → Max Events Per Tunnel
3. Clear old history: Delete events you don't need
4. Exclude frequently-changing tunnels: Don't track test tunnels

Host anonymization can improve performance by reducing search overhead on long hostnames.

Search & Filtering Issues¶

Search Not Finding Tunnels¶

If search isn't showing expected tunnels:

Search Fields Not Working¶

If specific fields aren't being searched:

1. Verify tunnel type: AWS vs SSH have different fields
2. Check for null values: Empty fields won't match
3. Try different keywords: Search ports, names, hosts
4. Restart StormTunnel: Sometimes search index needs refresh

Search Performance¶

If search is slow or laggy:

1. Reduce tunnel count: Archive old tunnels you don't use
2. Check system resources: Close other apps if memory is low
3. Restart StormTunnel: Clears cached search data
4. Report issue: If consistently slow, contact support

Clearing Filters¶

If you can't see all tunnels after searching:

1. Press Esc - Clears search immediately
2. Delete all text from search field
3. Click outside field - Sometimes focus issues
4. Restart app - If search field is stuck

Retry & Reliability Issues¶

Retry Not Working¶

If auto-retry isn't triggering:

Too Many Retry Attempts¶

If tunnels retry excessively:

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 connection issues

Retry Exhausted Errors¶

If you see "max retry attempts exceeded":

Check Connection History for error patterns - repeated errors indicate configuration issues.

When to Disable Retry¶

Consider disabling auto-retry if:

Retry with Different Auth Methods¶

If retries fail due to authentication:

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

Passwords aren't cached across app restarts. Retries may fail if password was deleted from Keychain.

Quick Fixes¶

Reset StormTunnel¶

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

Clear Known Hosts¶

If "Host key verification failed":

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

Force Quit¶

If StormTunnel is frozen:

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

Error Reference¶

Getting Help¶

Enable Debug Logging¶

For detailed troubleshooting:

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

Report an Issue¶

Include:

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

Contact: [email protected]

Related¶

• Creating Tunnels - Configuration options
• Authentication - SSH key setup
• AWS IAM Policies - AWS permissions