criticalFoundationSymptom-first#yaml#syntax#parse-error#workflow

Workflow YAML parse error - validation fails at start

Workflow run fails immediately with 'Invalid workflow file'

Likely source:configurationavailability

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Workflow run fails immediately with 'Invalid workflow file'
  • Actions tab shows 'There was an error while running the workflow file'
  • YAML parsing error: mapping values are not allowed here or bad indentation

GitHub Actions uses strict YAML 1.2. Common pitfalls: tabs, unquoted colons, unquoted on/off/yes/no (treated as booleans), and mismatched expression braces.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Workflow YAML syntax

    python3 -c 'import yaml; yaml.safe_load(open(".github/workflows/<file>.yml"))'

  • GitHub Actions validation error

    gh run view <RUN_ID> --log-failed | head -20

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • YAML parser shows 'mapping values are not allowed here' or 'bad indentation of a mapping'
  • Mixed tabs and spaces in the file

Confirm before fixing

cat -A .github/workflows/<file>.yml | grep '^I' | head -5
READ

Find tab characters in the file

Fix

expand -t 2 .github/workflows/<file>.yml > /tmp/ci.yml && mv /tmp/ci.yml .github/workflows/<file>.yml
CHANGE

Convert tabs to 2-space indentation

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
python3 -c 'import yaml; yaml.safe_load(open(".github/workflows/<file>.yml"))'
READ

Validate the YAML locally

2
cat -A .github/workflows/<file>.yml | grep '^I' | head -5
READ

Check for tabs in the file

3
grep -n '\${{' .github/workflows/<file>.yml | grep -v '}}'
READ

Find unclosed expressions

Prevention

  • Use an editor with YAML linting enabled (VS Code + YAML extension).
  • Run actionlint in a pre-commit hook or local CI step.
  • Quote all string values that contain colons, special characters, or look like booleans.
  • Validate YAML syntax before committing: python3 -c 'import yaml; yaml.safe_load(open(file))'.

Related runbooks

Same stack, same failure family — worth a skim.

GitHub Actions workflow not triggered on pushhigh

Push to main does not trigger any workflow run

GitHub ActionsFoundation3 causes
Open runbook
workflow_dispatch inputs not passed - secrets vs inputs mismatchmedium

Manually triggered workflow fails because input is empty

GitHub ActionsIntermediate2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.