GitHub Actions "Invalid workflow file ... error in your yaml syntax" in CI

By Kaveh Alemi·Latchkey

GitHub parses .github/workflows/*.yml before scheduling jobs. If the YAML does not parse, the run fails immediately with "Invalid workflow file" and "You have an error in your yaml syntax on line N", naming the offending line.

What this error means

The Actions run is annotated red with "Invalid workflow file: .github/workflows/ci.yml" and "You have an error in your yaml syntax on line N". No jobs start.

Invalid workflow file: .github/workflows/ci.yml#L12
You have an error in your yaml syntax on line 12

Common causes

A YAML parse error in the workflow

A tab, a bad indent, an unquoted colon, or a missing key at the reported line stops the parser before the workflow schema is even checked.

The reserved "on:" key mis-indented or mistyped

Breaking the top-level on: / jobs: / steps: structure produces a syntax error rather than a schema error.

How to fix it

Fix the YAML at the reported line

1. Open the workflow at the #L12 line the annotation links to.
2. Check for tabs, wrong indentation, or an unquoted colon in a value.
3. Push the fix; a valid file lets jobs schedule again.

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

Lint workflows in a pre-push or pre-commit hook

Run yamllint (or actionlint) on .github/workflows so syntax errors never reach GitHub.

- id: yamllint
  name: yamllint workflows
  entry: yamllint .github/workflows
  language: system

How to prevent it

• Lint workflow files locally with yamllint or actionlint.
• Never use tabs in workflow YAML.
• Quote values that contain colons.

Frequently asked questions

Related guides

References

• GitHub Actions documentation