Attempting to establish local end of tunnel on an interface + port combination already in use

[phil-odam]

Describe the bug

Arguably this 'bug' is in some ways more an inconvenience than an outright bug.

When attempting to establish a tunnel using aws ssm start-session listening on a local port that's already being listened on by another local process, the start-session command reaches Starting session with SessionId but then hangs at that point until the idle session timeout is exceeded (timeout specified at AWS Web Console > AWS Systems Manager > Session Manager > Preferences > Idle session timeout)

Expected Behavior

After printing out Starting session with SessionId: ... if unable to bind on the local interface + port combination my first thought would be I'd expect that Cannot perform start session: listen tcp ...: bind: address already in use then almost immediately be printed out and the awscli return an exit code.

Current Behavior

Currently, after executing the ssm start-session command the Starting session with SessionId line is printed but then all printing out stops until the idle session timeout is reached.

% aws ssm start-session \
      --target i-... \
      --document-name AWS-StartPortForwardingSessionToRemoteHost \
      --parameters host="...",portNumber="...",localPortNumber="..."

Starting session with SessionId: ...

Once the idle session timeout is reached the following is then printed out

SessionId: ... : Your session timed out due to inactivity and has been terminated.

Cannot perform start session: listen tcp ...: bind: address already in use

Reproduction Steps

Either attempt to establish local end of tunnel on an interface + port combination already in use on your machine or 'tie up' an interface + port combination so you can then see ssm's start-session behave in the way descibed.

# tie up 127.0.0.1:3306 so aws ssm start-session can't use it
nc -l 127.0.0.1 3306

You'll likely skip the following SSO steps, but for full clarity here's what we're doing

aws --profile ... sso login

export AWS_DEFAULT_PROFILE=...
export AWS_ACCOUNT_ID=...
export AWS_DEFAULT_REGION=...
export AWS_SDK_LOAD_CONFIG=1

aws sts get-caller-identity

Now attempt to establish the tunnel

aws ssm start-session \
    --target i-... \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters host="...",portNumber="3306",localPortNumber="3306"

Possible Solution

After printing out Starting session with SessionId: ... if unable to bind on the local interface + port combination that Cannot perform start session: listen tcp ...: bind: address already in use then almost immediately be printed out and the awscli return an exit code.

CLI version used

2.34.48

Environment details (OS name and version, etc.)

Python/3.14.5 Darwin/24.6.0 source/arm64