GitHub Actions "This run likely failed because of a workflow file issue"

When the workflow file itself is invalid (bad YAML, an unknown key, a malformed expression), the run fails at startup before any job begins, with a generic message pointing at the workflow file.

What this error means

A run shows a single startup failure annotation "This run likely failed because of a workflow file issue" and no jobs execute. The Actions tab lists the run as failed immediately.

This run likely failed because of a workflow file issue.

Common causes

Invalid YAML or unknown keys

A syntax error, wrong indentation, or an unrecognized top-level/job key makes the workflow unparseable.

Malformed expression or context reference

A ${{ }} expression has a syntax error or references something invalid, failing validation at parse time.

How to fix it

Validate the workflow file

1. Open the run's startup error to see the specific line and reason.
2. Run actionlint or a YAML linter locally on the workflow.
3. Fix indentation, unknown keys, and malformed expressions, then re-push.

# validate locally before pushing
actionlint .github/workflows/ci.yml

How to prevent it

• Lint workflows with actionlint in CI and pre-commit.
• Keep YAML indentation consistent (spaces, not tabs).
• Validate ${{ }} expressions before pushing.

Related guides