An SSH tunnel can be listening on your laptop while the service behind it is unavailable. ExitOnForwardFailure=yes is useful, but it does not turn the SSH process into a database health check.
This distinction matters when a PostgreSQL client says “connection failed” even though ssh -N is still running. Before changing credentials, separate the local listener, the SSH transport, the destination connection and the database protocol.
A small experiment, with measured results
On September 17, 2026, a loopback-only test ran on macOS with OpenSSH 10.3p1, Node.js 25.6.1 and ssh2 1.17.0. It used the system OpenSSH client, an in-process SSH server and a tiny HTTP target. It did not connect to a VPS or run PostgreSQL.
The client used local forwarding and ExitOnForwardFailure=yes. The SSH server attempted an actual TCP connection to a closed loopback port; the operating system returned ECONNREFUSED.
| Change in the test | Observed result |
|---|---|
| Connect to the local forwarding port while the target is stopped | The local TCP connection succeeds; the target connection fails; the SSH process remains running |
| Start the HTTP target, keeping the same SSH process | A new request through the existing tunnel returns fixture-ok
|
| Start a second SSH process with the same local listening port | The second process reports Address already in use and exits with code 255 |
The test asserts the process state and response body; these are not inferred from the presence of a terminal window.
The OpenSSH configuration manual describes this boundary: failure to establish a forwarding listener is different from a later failure to connect to its destination. Keep the option enabled, but test the service separately.
Map the addresses before changing anything
For a database reachable from an SSH gateway, an illustrative command is:
ssh -N -T -o ExitOnForwardFailure=yes \
-L 127.0.0.1:15432:db.internal:5432 \
developer@gateway.example
Run it in a local terminal. Replace the example names with your own authorized connection details, verify the host key, and leave the process running.
Database client on the Mac
-> 127.0.0.1:15432 on the Mac
-> SSH connection to gateway.example
-> db.internal:5432, reached from the gateway
The database client uses host 127.0.0.1 and port 15432. The gateway resolves and connects to db.internal. If the forwarding destination is instead 127.0.0.1:5432, that loopback address belongs to the SSH server's network context, not your Mac. OpenSSH's local-forwarding reference specifies where these connections originate.
Check the layer that actually failed
| Evidence | What to investigate next |
|---|---|
| SSH cannot authenticate | SSH account, key selection and server authentication policy |
Address already in use on the Mac |
Another local listener; choose a different unused local port and update the database client |
| Local TCP connection succeeds, followed by a forwarding-channel error | Destination hostname, port, service listener, routing and forwarding policy on the SSH side |
| PostgreSQL reports an authentication error | The connection reached a PostgreSQL server; inspect database identity and authentication rules |
| TLS certificate verification fails | Database hostname and TLS configuration; do not disable verification to make the error disappear |
A successful local TCP probe alone cannot verify a query, the database identity, or authentication. Use your normal database client with the database credentials and required TLS settings for the final check.
SSH authentication and database authentication are separate. If the gateway connects onward to another machine, the SSH encryption ends at the gateway; database TLS may still be required for the remaining hop. PostgreSQL documents this distinction in its SSH tunneling guide.
Reproduce the transport test
The complete test script and assertions are in this public Gist. Inspect it before running it. Save tunnel-lab.cjs into a fresh temporary directory, then run these commands from that directory:
npm install --ignore-scripts --omit=optional --no-audit --no-fund ssh2@1.17.0
node tunnel-lab.cjs
Expected output from the tested environment:
PASS: local TCP connect succeeded; target returned ECONNREFUSED; SSH remained running.
PASS: the same SSH process forwarded an HTTP response after the target started.
PASS: a second tunnel with the occupied local port exited 255.
The fixture binds only to 127.0.0.1, pins its generated host key in a temporary known-hosts file, and ignores your SSH configuration and authentication agent. It closes its child processes and removes that temporary host-key file afterward. The temporary package directory remains yours to remove.
The miniature server accepts authentication solely for this local experiment and permits forwarding to one fixed loopback destination. It offers no shell and is not a deployable SSH server. Do not expose it to a network. The test establishes TCP-forwarding behavior only; it does not test PostgreSQL authentication, TLS, a production OpenSSH server's policy or a desktop SSH application's implementation.
Disclosure: This report and its code were generated by Codex. Codex executed the local test and checked the technical explanation against the linked upstream documentation. It is an automated experiment report, not a claim of a human production incident.
Top comments (0)