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
- Lint workflow files in an editor and in a pre-commit hook.
- Copy steps from working workflows rather than typing structure from memory.
- Keep workflows small, and move shared logic into reusable workflows or composite actions.
- 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.
Related
- Refusing to Allow a GitHub App to Update Workflow: FixFix "refusing to allow a GitHub App to create or update workflow without workflows permission": use a PAT or App token with workflow write access.
- What Is a Reusable Workflow in GitHub Actions?A reusable workflow is a GitHub Actions workflow other workflows can call with inputs and secrets. Learn workflow_call syntax and common mistakes.
- What Is workflow_dispatch in GitHub Actions?workflow_dispatch is the GitHub Actions trigger that lets you start a workflow manually with inputs. Learn the syntax, CLI and API usage and pitfalls.
- Cache Service Responded With 429: FixFix "Failed to restore: Cache service responded with 429" in GitHub Actions: too many cache requests. Upgrade actions/cache, restore once, save once.