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.

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