GitHub Actions Runner Errors — Workflow Failures and Self-Hosted Runner Issues

Fix GitHub Actions workflow errors including runner connectivity issues, container job failures, secret access problems, and artifact upload failures. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: GitHub Actions runners execute workflow jobs — GitHub-hosted or self-hosted. Self-hosted runners require persistent connectivity to GitHub's API endpoints. Container jobs (runs-on: ubuntu-latest with container:) have different filesystem and network behavior. Secrets are available as environment variables but not in fork PRs for security. Actions cache and artifacts have size limits that can cause failures. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Self-hosted runner offline or unable to connect to GitHub API endpoints. Secret not available in the workflow context (wrong scope, fork PR, or not configured). Docker container image not found or registry authentication failed for container jobs. Artifact or cache size exceeding the 10GB per repository limit. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check runner status: repository Settings > Actions > Runners — verify runner is online. Debug workflow: add 'ACTIONS_STEP_DEBUG: true' to env or enable debug logging in repository secrets. For secret issues: verify secret names match the workflow reference and the secret is at the correct scope (repo/org/environment). Self-hosted runner logs: check _diag/ directory in the runner installation folder for detailed logs. Use 'act' tool to test workflows locally before pushing: 'act -j build' runs the build job locally. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Linux Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.