# Runpod SSH not working: diagnose one connection layer at a time

Diagnose Runpod SSH failures by checking current Pod state, transport mode, mapped ports, sshd and public-key authentication in a clear order.

Author: Retrivium team
Updated: 2026-11-01
Canonical URL: https://retrivium.ai/journal/runpod-ssh-connection-debug/
Language: en

When Runpod SSH fails, save the exact error and compare your command with the current Connect information. A timeout, refused connection and `Permission denied` describe different stages. Replacing a key before identifying the stage often changes nothing useful.

## Verify the Pod and access mode

Wait for deployment and the required service inside the container. Establish whether you are using the basic proxy or direct TCP SSH, and whether the task is terminal work, file transfer or an IDE connection.

Check the Pod ID and current external parameters. After replacement, a saved SSH profile may still point to the previous resource. Compare it with a complete current command before assuming the new environment has the same fault.

## Diagnose one layer at a time

| Observation | First investigation |
| --- | --- |
| Connection times out | Route, current address, mapped port and readiness |
| Connection is refused | Listening port and SSH-server process |
| Permission denied | User, selected private key and matching public key |
| Terminal works but SFTP fails | Whether the chosen transport supports full SSH |

This table sets an investigation order, not a unique explanation for every failure. Corporate networks, local client settings and custom images can add constraints. Keep each trial controlled so a successful change has an interpretable cause.

## Check authentication without exposing secrets

Confirm that Credentials contains the complete public line rather than a fingerprint. The client must use its matching private file. If an SSH agent offers several unrelated keys, select the intended identity explicitly and inspect diagnostic output.

A password prompt is not a reason to invent a container password. First investigate key authentication. Remove secrets before sharing logs; nobody needs the private-key contents to compare the selected identity and public configuration.

## Verify the server and mapped port

Direct SSH needs the external TCP port mapped to the internal SSH service. Publishing a port does not launch `sshd`. A custom image can run compute successfully yet lack a configured SSH server, so a valid key alone will not make that path work.

Preserve a minimal known-good access configuration, including server startup and log location. A support report should include Pod ID, time, mode, exact error and previous checks. Keep private material out of it. That report distinguishes an image problem, transport limitation and authentication failure without opening unrelated ports or changing the whole environment.

## Turn the check into a practical next step

The error message identifies the next layer to inspect. Change one connection parameter at a time and preserve the result rather than rotating keys blindly.

For the documented details, consult the [primary documentation](https://docs.runpod.io/pods/configuration/use-ssh); [configuration reference](https://docs.runpod.io/pods/configuration/expose-ports). Continue with [runpod ssh public key setup](/journal/runpod-ssh-public-key-setup/) and [runpod private port forward](/journal/runpod-private-port-forward/).