Skip to content

Connection Testing

Use Connection Test to check whether StormTunnel can start a tunnel with its saved settings. It briefly starts a separate test tunnel and stops it automatically; your saved tunnel remains disconnected.

A successful test does not log in to your database or run a query. To verify the database endpoint and database credentials, start the tunnel and connect your database client to 127.0.0.1 and the tunnel's local port.

Run a Test

  1. Select a disconnected tunnel in the main window. Disconnect an active tunnel first; Test is unavailable while it is connected.
  2. Click Test next to Connection Test under Status & Connection Test.
  3. Review the result, duration, and any reported error under Test Details. Retry runs the test again and Clear removes the result.

The test checks the tunnel configuration, whether the local port is available, and whether StormTunnel can bring the tunnel to its ready state. For an AWS tunnel, this tests starting a Session Manager session; the database or service may still need to be checked by connecting a client through the local port.

Before You Test

For AWS Session Manager, confirm:

  • The selected AWS profile is signed in. In the tunnel editor, Validate checks credentials and tries to verify the managed instance's status without saving. Describe permission limits can leave status unverified. See AWS IAM permissions.
  • The region and EC2 instance ID are correct.
  • The instance is online in Systems Manager.
  • The EC2 instance can reach the destination host and port.

For SSH, confirm the host, port, and authentication method. The server must be reachable from your Mac.

Common Failures

  • Local port is in use: Select a different local port or stop the process using it.
  • AWS access denied: Ask your administrator to check the user or role's Session Manager permissions.
  • AWS instance unavailable: Check the instance's Systems Manager status and region.
  • Remote connection refused or timed out: Check the destination host, port, DNS, routes, and security groups from the EC2 instance.
  • SSH authentication failed: Check the selected key or password and verify that the server authorizes it.

See Troubleshooting for detailed steps.