A self-hosted GitHub Actions runner goes offline or stops by itself
OfflineShort answer
GitHub marks a runner Offline when the machine is down, the runner application is not running, or it cannot reach GitHub. Check the service with systemd, launchd or Windows services, run config.sh --check for connectivity, and read the newest Runner_ log in the _diag folder.
Fix it fast
1Find out which cause you have
On the runner machine, look at the service and its latest log lines. They tell you whether the runner is running at all.
cat ~/actions-runner/.service systemctl --type=service | grep actions.runner2Match what you see, then jump to its fix
- 1
The service is inactive or failed, and no process shows for the runnerThe runner service is not runningFix - 2
The service runs but the runner stays OfflineThe runner cannot communicate with GitHubFix - 3
A SelfUpdater entry in a Runner_ log near the time the runner went quiet, or automatic updates are switched offThe runner application is out of date or its update failedFix
- 1
What does the error look like?
OfflineRunner status in Settings > Actions > Runners shows Offline
Cause 1 of 3
The runner service is not running
1Check
The runner application must be running for GitHub to see it. On Linux, follow the service's journal using the name stored in the .service file; on macOS, svc.sh status shows a process ID when it runs.
sudo journalctl -u "$(cat ~/actions-runner/.service)" -n 50 --no-pager2Fix
Fix what the log shows, then start the service again. On macOS, ./svc.sh status confirms it; on Windows use Get-Service on the service name.
sudo systemctl restart "$(cat ~/actions-runner/.service)"3Verify
The runner no longer shows Offline in Settings > Actions > Runners.
systemctl status "$(cat ~/actions-runner/.service)"Confirmed by docs.github.com
Cause 2 of 3
The runner cannot communicate with GitHub
1Check
Run the connectivity check from the runner folder. It prints PASS or FAIL for each service, and failing checks leave details in _diag.
./config.sh --check --url https://github.com/OWNER/REPO --pat YOUR_TOKEN2Fix
Allow outbound HTTPS on port 443 to the hostnames GitHub lists for runners (github.com, api.github.com and *.actions.githubusercontent.com are the essential ones), then restart the runner.
tail -n 50 ~/actions-runner/_diag/Runner_*.log3Verify
Run the check again and expect PASS on every line.
./config.sh --check --url https://github.com/OWNER/REPO --pat YOUR_TOKENConfirmed by docs.github.com
Cause 3 of 3
The runner application is out of date or its update failed
1Check
The runner updates itself when a job is assigned, or within a week of a release. With automatic updates off, a runner more than 63 days behind gets no jobs. Update entries appear in the Runner_ logs and the SelfUpdate logs in _diag.
grep -h SelfUpdater ~/actions-runner/_diag/Runner_*.log | tail -n 202Fix
Read the failure in the log, fix it (disk space, permissions, network), and restart the service. Keep the OS and other software updated yourself.
sudo systemctl restart "$(cat ~/actions-runner/.service)"3Verify
The newest Runner_ log shows a clean start.
ls -t ~/actions-runner/_diag | headConfirmed by docs.github.com
How do I stop it coming back?
- Run config.sh --check again after any move to a new network or proxy.
- Send _diag logs off the machine, so you can read them after the machine is replaced (needed for ephemeral runners).
- Alert on a runner staying Offline for more than a few minutes.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
A local composite action in GitHub Actions cannot be found
The action folder is in the repository but the runner reports that its action.yml cannot be found
A local action is read from the checked-out repository.
3 causes, each with a fixServers
A GitHub Actions workflow builds the Docker image but cannot push it
The push step fails right after the login step
Four things stop a push from GitHub Actions: build-push-action does not push unless push is true, the Docker Hub login used a password instead of an access token, the workflow token lacks packages write for ghcr.io, or the run comes from a fork, where the token is read-only.
4 causes, each with a fixServers
A GitHub Actions step with shell: pwsh or powershell fails on Linux
shell: powershell on a Linux runner
GitHub starts a step with the shell name you give.
3 causes, each with a fixServers
Make a GitHub Actions step run after a failure, and keep the job failed
The job is green even though a step failed (continue-on-error)
A step with no if: condition gets success() by default, so it is skipped once any earlier step fails.
3 causes, each with a fixServers
GitHub Actions step fails writing to GITHUB_OUTPUT
Error: Invalid format '...'
The runner reads GITHUB_OUTPUT line by line, and every entry must be name=value or a name<<DELIMITER block.
3 causes, each with a fixServers
poetry command not found right after installing it in a GitHub Actions step
Poetry installs without error in one step, and the next step cannot find it
The official installer puts the poetry command in $HOME/.local/bin, which is not always on PATH.
3 causes, each with a fix