The GitHub Actions self-hosted runner service is failing to start because the underlying process that manages the runner is crashing due to an unexpected termination signal.
Cause 1: Insufficient Disk Space
The runner process requires temporary disk space to download job artifacts and execute scripts. If the disk is full, the process will be unable to create necessary files and will crash.
Diagnosis:
df -h /path/to/runner/data
Look for partitions with 100% usage, especially /tmp or the partition where your runner is installed.
Fix: Free up disk space by deleting old logs, temporary files, or unused Docker images. For example, to remove old Docker images:
docker image prune -a
This frees up space by removing all unused images, allowing the runner to operate.
Cause 2: Corrupted Runner Installation
A corrupted runner installation can lead to critical files being missing or unreadable, preventing the service from initializing correctly.
Diagnosis:
Check the runner’s log files for specific file not found errors or permission denied errors related to executables within the runner directory. The logs are typically located at /path/to/runner/.runner/_diag/Runner_*.log.
Fix: Re-download and re-install the runner. This ensures all necessary files are present and correctly formed.
- Stop the runner service.
- Remove the existing runner directory.
- Download the latest runner release from GitHub.
- Re-configure the runner using the
config.shscript with your GitHub organization or repository. This replaces any corrupted files with fresh ones, allowing the runner to start.
Cause 3: Incorrect Permissions on Runner Directory
The user account running the self-hosted runner service might not have the necessary read/write/execute permissions on the runner’s installation directory or its subdirectories.
Diagnosis: Check the permissions of the runner directory and its contents:
ls -ld /path/to/runner
ls -l /path/to/runner
Ensure the user running the service (often _runner or a dedicated user) has ownership and appropriate permissions (e.g., rwxr-xr-x).
Fix:
Grant the correct ownership and permissions to the runner directory. For example, if the runner is run by the user actionsrunner:
sudo chown -R actionsrunner:actionsrunner /path/to/runner
sudo chmod -R u+rwX /path/to/runner
This ensures the runner process can access and modify the files it needs to operate.
Cause 4: Outdated Runner Version with Incompatible Dependencies
An older version of the self-hosted runner might have dependencies that are no longer compatible with the host operating system’s libraries or newer GitHub Actions features.
Diagnosis:
Review the runner’s log files for errors related to shared libraries (e.g., libssl.so, libc.so) or specific API calls that are failing. The logs are usually in /path/to/runner/.runner/_diag/.
Fix: Update the runner to the latest version.
- Stop the runner service.
- Download the latest runner release.
- Replace the existing runner binaries with the new ones.
- Re-configure if necessary (though often just replacing binaries is sufficient). This ensures the runner is using up-to-date code and dependencies compatible with the GitHub Actions platform.
Cause 5: Network Connectivity Issues to GitHub API
The runner service needs to communicate with GitHub’s API to fetch jobs and report status. If this communication is blocked or unreliable, the runner process might fail to start or stay alive.
Diagnosis:
Attempt to curl the GitHub API endpoints from the runner host.
curl https://api.github.com/meta
Check for timeouts, connection refused errors, or SSL certificate verification failures. Also, check firewall rules and proxy configurations.
Fix:
Ensure the runner host can reach api.github.com and uploads.github.com on port 443. If using a proxy, configure it for the runner:
# In .env file in the runner directory
# HTTP_PROXY=http://your.proxy.server:port
# HTTPS_PROXY=http://your.proxy.server:port
This allows the runner to establish a stable connection with GitHub’s services.
Cause 6: Systemd Service File Misconfiguration
If you’re running the runner as a systemd service, an incorrect service file can prevent it from starting or cause it to crash immediately after launch.
Diagnosis: Check the status of the systemd service:
sudo systemctl status actions.runner.service
Examine the ExecStart line in the service file (usually located at /etc/systemd/system/actions.runner.service or similar) for typos, incorrect paths, or missing arguments.
Fix:
Correct the actions.runner.service file. Ensure the User and Group directives match the user running the runner, and that the ExecStart path points to the correct run.sh script within your runner directory. After editing, reload systemd and restart the service:
sudo systemctl daemon-reload
sudo systemctl restart actions.runner.service
This ensures the service is started with the correct parameters and user context.
The next error you’ll likely encounter is a Resource temporarily unavailable error from the docker command if you are using Docker for your jobs, because the runner service itself is now running but the worker processes it spawns cannot create containers.