Debugging with SSH: How to Rerun a Job with SSH

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 `https://app.circleci.com/settings/user/job-ssh-keys`
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

See: Why Can't I See The ReRun Via SSH Option?

"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 "your_email@example.com"

Add the new key to your VCS account and to CircleCI at https://app.circleci.com/settings/user/job-ssh-keys.

See: Permission error when trying to SSH into a job

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

See: Preserve Environment Variables While Debugging With SSH

"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.

See: Context error preventing job re-run with SSH

SSH not working from Warp terminal (macOS)

Known compatibility issue. Use the standard macOS Terminal or iTerm2 instead.

See: Problems connecting to SSH session using Warp terminal for macOS

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}'

See: How to see running SSH jobs

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.

See: Can I adjust the default timeout of jobs in an active SSH session?

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

Additional Resources