Skip to content

Invalid Workflow File: YAML Syntax Error Fix

Last updated

Invalid workflow file means GitHub could not parse or validate your workflow YAML, so no jobs ran at all. The run shows a red failure with no steps, and the message names the file and usually a line. The cause is nearly always indentation, a value in the wrong place, or a malformed expression. This page lists the common messages and a way to catch them before you push.

The exact message

Invalid workflow file: .github/workflows/ci.yml#L12
You have an error in your yaml syntax on line 12
The workflow is not valid. .github/workflows/ci.yml (Line: 14, Col: 9): Unexpected value 'run'
The workflow is not valid. .github/workflows/ci.yml (Line: 8, Col: 5): Required property is missing: runs-on

The line number is where the parser noticed the problem. The real mistake is often on the line before.

Cause 1: indentation

YAML uses spaces, never tabs. A step key at the wrong depth makes run look like a sibling of steps:

# Wrong
steps:
  - uses: actions/checkout@v4
  run: npm test

# Right
steps:
  - uses: actions/checkout@v4
  - run: npm test

Cause 2: a colon or special character in an unquoted value

A value that contains : or starts with *, &, !, { or % needs quotes.

# Wrong
- name: Build: release
# Right
- name: "Build: release"

A run: command with a colon is fine when written as a block:

- run: |
    echo "status: ok"

Cause 3: a missing required key or an unknown key

Every job needs runs-on (or uses for a reusable workflow) and steps. Keys are case sensitive, and a typo such as step: or runs_on: fails. needs: must name a job that exists in the same file.

Cause 4: expressions

An unclosed ${{, a stray single quote, or a function that does not exist fails the whole file. Expressions in if: can be written with or without ${{ }}, but an expression that starts with ! must be wrapped, because YAML reads a leading ! as a tag:

if: ${{ !cancelled() }}

Strings in expressions use single quotes: ${{ github.ref == 'refs/heads/main' }}.

Cause 5: on: trigger mistakes

The on: key accepts a name, a list or a map. Filters such as branches go under the event:

on:
  push:
    branches: [main]
  pull_request:

Using both branches and branches-ignore for the same event is not allowed.

Cause 6: context not available where you used it

Some contexts exist only in certain places: env cannot be used in a jobs.<id>.if, and secrets cannot be used in an if expression at job level directly. The message says "Unrecognized named-value" and names the context.

Catch it before you push

Run a workflow linter locally. actionlint understands the schema, shell snippets and expressions:

docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

or install it with Homebrew (brew install actionlint) and run actionlint. You can also run it in CI on workflow changes:

- uses: actions/checkout@v4
- run: bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) && ./actionlint -color

Editors with the YAML extension and GitHub's workflow schema also highlight errors as you type.

How to prevent it

  1. Lint workflow files in an editor and in a pre-commit hook.
  2. Copy steps from working workflows rather than typing structure from memory.
  3. Keep workflows small, and move shared logic into reusable workflows or composite actions.
  4. Review workflow changes in a pull request, where the run fails visibly before merge.

FAQ

Why did my workflow not run at all?

An invalid file prevents any run. Look at the Actions tab for a failed run with the file name, or the annotation on the commit.

Why does GitHub point at the wrong line?

The parser reports where it gave up. Look at the line above, and at indentation.

Can I validate YAML with a generic YAML linter?

It catches syntax errors but not GitHub-specific rules such as missing runs-on. Use actionlint for those.

My file is valid but the job is skipped, why?

That is a different problem: a trigger filter, a path filter or an if: condition. See waiting for a runner if the job is stuck rather than skipped.