Overview
CircleCI allows you to rerun any job with SSH access enabled, so you can log in to the build environment and inspect files, environment variables, running processes, and more. This guide covers how to trigger an SSH rerun, connect successfully, and resolve the most common problems.
Container Runner users: SSH debugging is not supported for jobs running on Container Runner. This is a current product limitation.
How to Rerun a Job with SSH
Navigate to the failing job in the CircleCI UI (you must be at the job level, not the workflow level).
Click the Rerun dropdown in the top-right corner and select Rerun job with SSH.
A new job will start in the same pipeline. Expand the Enable SSH step in the job output to see your connection command:
ssh -p <port> <ip-address>
Connect using the SSH key linked to your GitHub, GitLab, or Bitbucket account.
Once connected, the job pauses at the Wait for SSH step. Explore the environment, then manually cancel the job when finished.
Session time limits:
SSH connection available for 10 minutes after the job completes (if not yet connected).
Once connected, session stays open for up to 2 hours.
Always cancel SSH jobs manually when done — they consume a concurrency slot while running.
Troubleshooting
"Rerun job with SSH" button is not visible
Cause | Fix |
SSH disabled for the project | Re-enable via API — see Disable re-run job with SSH |
No SSH key on your CircleCI account | Add at |
You're at the workflow level, not job level | Navigate into the specific job, then use the Rerun dropdown |
Insufficient permissions | Requires Write or higher — check under Org Settings → People |
"Permission denied (publickey)" when connecting
Wrong key being offered — check which key your agent is presenting and specify the correct one:
ssh -p <port> <ip-address> -v # Look for: "Offering public key: <path>"# Force the correct key: ssh -i ~/.ssh/your_correct_key -p <port> <ip-address>
Deprecated ssh-rsa (SHA-1) key — OpenSSH 8.8+ no longer accepts this. Generate a new key:
ssh-keygen -t ed25519 -C "[email protected]"
Add the new key to your VCS account and to CircleCI at https://app.circleci.com/settings/user/job-ssh-keys.
Connection refused or timed out
The 10-minute connection window has expired. Trigger a new SSH rerun. Watch the Enable SSH step in the job output — the connection command appears as soon as it's ready.
Connected, but $PATH or environment variables are wrong
SSH sessions run through the system bash profile (/etc/profile), which can reset variables set in your Dockerfile via ENV. Fix this permanently in your image:
RUN echo 'export PATH="/home/circleci/.local/bin:/home/circleci/bin:${PATH}"' \
> /home/circleci/.bash_profile && \
chmod +x /home/circleci/.bash_profile"Context error" when trying to rerun with SSH
Context security group restrictions apply to SSH reruns too. Verify you have access to the context under Org Settings → Contexts, or ask an org admin.
SSH not working from Warp terminal (macOS)
Known compatibility issue. Use the standard macOS Terminal or iTerm2 instead.
SSH jobs are consuming my concurrency limit
SSH jobs count against your org's concurrency. Find and cancel any forgotten ones:
curl -G "https://circleci.com/api/v1.1/recent-builds?shallow=true" \
-H "Circle-Token: <YOUR_API_TOKEN>" \
| jq '.[] | select(.why == "ssh") | select(.status == "running") | {build_url, build_num}'Can I extend the 2-hour session limit?
No — this is a hard platform limit. Cancel, commit your findings, and start a new SSH rerun if more time is needed.
Connection closed due to executable file not found in $PATH
Error: exec: "export": executable file not found in $PATH Connection to x.x.x.x closed
If you encounter the failure above, please add the -t bash or -t /bin/sh postfix.
ssh -p <port number> x.x.x.x -t bash ssh -p <port number> x.x.x.x -t /bin/sh