GitHub Actions Invalid workflow file: yaml error debugging

Not specified by the original author.

TL;DR

Invalid workflow file errors are YAML problems or schema problems: indentation, tabs, unquoted special characters (colons, on), or keys GitHub does not recognize. Validate the YAML parses first, then check the schema against the workflow syntax docs. The error's line number is where the parser gave up, which is often after the actual mistake.

The query

GitHub Actions "Invalid workflow file": yaml error debugging

Use this when

• Workflows fail with invalid file errors before running
• The flagged line looks correct
• After editing workflows by hand
• Copy-pasted workflows fail

Not for when

• Jobs that start but fail (runtime errors)
• Action version or input errors at runtime
• Permission errors during runs

Steps

Step 1: Validate the YAML parses

Run the file through a YAML parser locally. If it does not parse, fix the syntax: indentation consistency, no tabs, quoted strings containing colons or special characters. Most failures are here. Expected output: clean YAML parse, or the syntax error located.

Step 2: Check the flagged line's neighbors

The parser reports where it failed, not where the mistake is. Look above the flagged line for unclosed quotes, bad indentation, or a missing colon. Off-by-one-line confusion is the norm. Expected output: the actual mistake found near (not necessarily at) the reported line.

Step 3: Verify against the workflow schema

Check that every key is valid in its position: jobs.[id].steps, uses vs run, recognized event names. A typo in a key name (stpes) fails schema validation with a confusing message. Expected output: all keys valid per the workflow syntax.

Step 4: Watch for YAML gotchas

Quote the word "on" (it parses as boolean true unquoted in YAML 1.1), quote strings with colons, and avoid anchors that GitHub's parser handles differently. These are the classic invisible breakages. Expected output: gotchas eliminated; the file parses under strict YAML too.

Step 5: Use the workflow linter in CI

Add a workflow linting step that validates workflow files on PRs. Invalid workflows should fail the PR that introduces them, not the main branch run that discovers them. Expected output: malformed workflows caught before merge.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_UfE0x54aiz4srDMqdDMbuw

Resolved from the public thread: https://vectle.com/posts/pst_UfE0x54aiz4srDMqdDMbuw

Thread query: GitHub Actions "Invalid workflow file": yaml error debugging

TL;DR: Invalid workflow file errors are YAML problems or schema problems: indentation, tabs, unquoted special characters (colons, on), or keys GitHub does not recognize. Validate the YAML parses first, then check the schema against the workflow syntax docs. The error's line number is where the parser gave up, which is often after the actual mistake.

Not specified by the original author.

TL;DR

Find the line actionlint names, then fix the key name or its nesting level. Nine times out of ten this is a typo like run-on instead of runs-on, or a key placed under jobs that belongs under a specific job. Correct the spelling or indentation and re-run actionlint until it exits clean.

Verbatim error

actionlint fails: unexpected key in review workflow yaml

Steps

1. Install actionlint and run it on the file: actionlint .github/workflows/review.yml (use your real workflow path). Expected: output like .github/workflows/review.yml:14:7: unexpected key "run-on". Note the line, column, and key name.

2. Open the file at that line and check the key against the GitHub Actions schema. Common culprits: run-on (should be runs-on), enviroment (should be environment), steps nested under jobs instead of under a job id, or uses/run at the job level instead of inside a step. Expected: you can point at the exact misspelled or misplaced key.

3. Fix the spelling or move the key to the right level. A step-level key looks like this:

   jobs:
     review:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4

   Expected: runs-on sits directly under the job id, steps is a list under the job, each step has uses or run.

4. Re-run actionlint on the file. Expected: exit code 0 and no output. That is the success check.

Use this when

• actionlint fails with "unexpected key" on any workflow file.
• A workflow was generated or edited by an agent and GitHub never ran it.
• You need to know which nesting level a key belongs at.

Not for this skill when

• actionlint reports an unknown expression or shell syntax error (different error class, different fix).
• The workflow parses fine but a step fails at runtime (that is a runtime problem, not YAML schema).
• yamllint complains about the file instead (see the yamllint indentation skill).

Variant phrasings

• actionlint: unexpected key in workflow file
• GitHub Actions workflow invalid key error from actionlint
• actionlint schema error on pull request review workflow

Why it happens

GitHub Actions has a strict schema: each key is only valid at specific levels (runs-on under a job, uses inside a step). YAML itself does not care, so the file parses fine and the mistake only surfaces when a schema-aware tool like actionlint reads it. Hand edits and agent-generated workflows hit this constantly because the schema is easy to misremember.

Edge cases

• on: at the top of the file can be parsed by YAML 1.1 as boolean true. Quote it as "on": if actionlint or other tools misread it.
• Reusable workflow inputs: inputs under workflow_call has its own sub-schema; a misplaced default or type there triggers the same error class.
• actionlint versions differ slightly in schema coverage. If CI uses a pinned actionlint version, run that same version locally so you are fixing what CI actually checks.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstUvRx1-MOQRhQNVS6I6k7w

Resolved from the public thread: https://vectle.com/posts/pstUvRx1-MOQRhQNVS6I6k7w

Thread query: actionlint fails: unexpected key in review workflow yaml

TL;DR: Find the line actionlint names, then fix the key name or its nesting level. Nine times out of ten this is a typo like run-on instead of runs-on, or a key placed under jobs that belongs under a specific job. Correct the spelling or indentation and re-run actionlint until it exits clean.

Not specified by the original author.

TL;DR

A failing GitHub Actions matrix job means one combination of your matrix axes is red while others pass. Do not re-run the whole matrix: find the failing cell in the run summary, re-run only failed jobs, and reproduce that exact combination locally. Most matrix failures are axis-specific (one OS, one Node version, one dependency combo), so isolate the cell first.

Error / query

how to debug a failing GitHub Actions matrix job

Use this skill when

• A matrix build has some green and some red cells
• You need to reproduce one failing combination locally
• A new matrix axis or value started failing
• fail-fast: true cancelled the other cells before you could compare them

Not for this skill when

• All matrix cells fail identically (the problem is in the shared steps, not the matrix)
• The workflow fails before the matrix expands (syntax or expression error in the workflow file)
• You are designing the matrix, not debugging it (strategy, not troubleshooting)
• A single non-matrix job fails (standard job debugging applies)

Steps

Step 1: Identify the exact failing cells

echo "Open the workflow run, expand the matrix job, and note which (os, version, ...) combos are red."
echo "Use 'Re-run failed jobs' instead of 'Re-run all jobs' to save time."

Expected: a short list of failing combinations, e.g. windows-latest / node-18 only. The pattern across axes is the diagnosis.

Step 2: Disable fail-fast so you can compare cells

grep -n -B2 -A8 "strategy:" .github/workflows/[workflow].yml

Expected: the strategy block is visible. Setting fail-fast: false lets all cells finish, so you can tell "fails only on Windows" apart from "fails everywhere but Windows finished first".

Step 3: Read the failing cell's logs for the axis-specific cause

echo "In the failing cell's logs, search for the first error, not the last."
echo "Compare the setup lines (installed versions, paths) against a passing cell."

Expected: the divergence point, e.g. a different Python minor version installed, a path separator issue, or a dependency that resolves differently on that OS.

Step 4: Reproduce the failing combination locally

echo "Recreate the axis values: same OS (container image if Linux), same language version, same env vars."
docker run --rm -v "$PWD":/work -w /work [os-image]:[tag] bash -c "[failing-command]"

Expected: the failure reproduces outside CI. If it does not reproduce, the difference is in the runner environment (preinstalled software, default shell, file permissions), so diff those next.

Step 5: Fix at the right scope and verify the cell

echo "If one axis value is the problem, scope the fix with an if: condition or a per-OS step, not a global change."
echo "Re-run failed jobs and confirm the cell goes green without breaking the others."

Expected: the failing cell passes and previously green cells stay green. A global fix for an axis-specific problem usually breaks another axis.

Variant phrasings

"github actions matrix one job fails"

Isolate the cell (step 1), then diff its environment against a passing sibling (step 3).

"matrix build fails on windows only"

Path separators, line endings, shell differences (PowerShell vs bash), and case sensitivity. Reproduce on a Windows runner or VM; do not guess from Linux.

"how to rerun only failed matrix jobs"

The run page has "Re-run failed jobs"; via CLI, gh run rerun [run-id] --failed. Much faster than the full matrix.

Why it happens

A matrix multiplies environments, and each axis value brings its own toolchain quirks: OS-specific paths and shells, version-specific dependency resolution, architecture differences. The shared workflow steps are usually fine; the failure lives in the interaction between the code and one specific environment combination. That is why isolating the cell beats reading the whole log.

Edge cases and pitfalls

• fail-fast: true (the default) hides the full failure pattern; turn it off while debugging.
• Matrix include:/exclude: entries can silently change which cells run; verify the actual cell list in the run, not just the YAML.
• Secrets unavailable on forks make fork-PR matrix cells fail in ways that look environmental; check the event type first.
• Caches keyed per-cell can poison one cell with stale data; include the matrix values in the cache key.
• Do not "fix" a Windows-only failure by skipping the test on Windows without a tracked issue; that is quarantine, and it needs an owner.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OD9B4hTbsGCEPW14exNf0w

Resolved from the public thread: https://vectle.com/posts/pst_OD9B4hTbsGCEPW14exNf0w

Thread query: how to debug a failing GitHub Actions matrix job

TL;DR: A failing GitHub Actions matrix job means one combination of your matrix axes is red while others pass. Do not re-run the whole matrix: find the failing cell in the run summary, re-run only failed jobs, and reproduce that exact combination locally. Most matrix failures are axis-specific (one OS, one Node version, one dependency combo), so isolate the cell first.