GitHub Actions "workflow run failed: startup_failure"

By Kaveh Alemi·Latchkey

startup_failure means GitHub could not even begin the run. The cause is either the workflow file failing to compile on that ref, or a transient backend error preparing the run.

What this error means

A run shows conclusion startup_failure with no job logs, often with no obvious step output.

The workflow run failed: startup_failure
This run could not be started. The workflow file may be invalid, or a system error occurred.

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

Common causes

Invalid workflow file on the triggering ref

A YAML or schema error on the branch that triggered the event prevents the run from compiling.

Transient backend error

A GitHub-side system error during run preparation produces startup_failure even with a valid file.

How to fix it

Validate the workflow on the triggering ref

1. Open the workflow file on the exact branch/ref that triggered the event and check for YAML errors.
2. Lint it locally with actionlint.
3. Fix any schema issues and push.

Re-run on transient failures

1. If the file is valid, re-run all jobs; startup_failure from a backend hiccup usually clears on retry.
2. On managed runners, Latchkey auto-retries transient startup failures so a single infra blip does not fail your pipeline.

The failures that are not your workflow

• Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
• Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
• A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
• A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

How to prevent it

• Run actionlint in CI on workflow changes to catch invalid files before merge.
• Treat isolated startup_failure with a valid file as transient and retry.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions