ARC "ephemeral runner failed to start" in CI

By Daniel Zoghalchali·Latchkey

ARC created an EphemeralRunner and its pod, but the runner container could not start the Actions runner process. The pod may crash, stay in error, or exit before registering.

What this error means

The EphemeralRunner shows a failed phase and the runner pod logs an error before the runner listener starts. The job stays queued while ARC recreates the runner.

ERROR ephemeral runner failed to start
  {"ephemeralrunner": "arc-runner-set-xxxx", "reason": "runner registration
  failed, config.sh exited with code 2"}

Common causes

Registration during startup fails

config.sh runs at pod start to register the runner; a bad token, network block, or scope error makes it exit non-zero.

A broken custom runner image

A custom image missing the runner binary or with a bad entrypoint cannot launch the runner process.

How to fix it

Read the runner pod logs

1. Describe the EphemeralRunner to see the failure reason.
2. Read the runner container logs for the config.sh or startup error.
3. Fix the credential, egress, or image issue the logs name.

kubectl describe ephemeralrunner -n arc-runners <name>
kubectl logs -n arc-runners <runner-pod> -c runner

Validate the runner image

If using a custom image, confirm it derives from the official runner image and keeps the runner binary and entrypoint intact.

How to prevent it

• Base custom runner images on the official ARC runner image.
• Keep credentials and egress valid so registration succeeds at start.
• Test image changes on a small scale set before rolling out.

Frequently asked questions

Related guides

References

• GitHub Actions documentation