Introduction

This GitHub Actions error happens before the workflow can even start. GitHub reads the workflow file as YAML, and if one key, indent level, or multi-line block is malformed, the parser stops with mapping values are not allowed here. The line number is useful, but the real mistake is often a few lines earlier where the YAML structure first became invalid.

Symptoms

  • GitHub says the workflow is invalid before any job appears
  • The error references mapping values are not allowed here
  • A recent edit added environment variables, matrix settings, or a multi-line run block
  • The same workflow worked before a small formatting change

Common Causes

  • A key is missing its colon or has inconsistent indentation
  • A multi-line shell script was written without | under run
  • A value containing : or other YAML-sensitive characters was left unquoted
  • Tabs were introduced into a file that should use spaces only

Step-by-Step Fix

  1. 1.Inspect the lines just before the reported error
  2. 2.The YAML parser often fails on the first line that becomes impossible to interpret, not the first line that was actually written wrong.

```yaml # Wrong - name Build run: npm test

# Correct - name: Build run: npm test ```

  1. 1.**Convert multi-line run commands to a proper block**
  2. 2.This is one of the most common ways to break workflow YAML after adding extra commands.
yaml
- name: Build and test
  run: |
    npm ci
    npm run build
    npm test
  1. 1.Quote values that include colons or ambiguous YAML syntax
  2. 2.Environment values and strings with embedded punctuation can be parsed as mappings if left bare.
yaml
env:
  RELEASE_NOTE: "Version 2.0: new rollout wave"
  1. 1.Validate the workflow locally before pushing again
  2. 2.Local linting is faster than repeated pushes and usually gives better error positioning.
bash
actionlint .github/workflows/*.yml

Prevention

  • Use spaces only, not tabs, in every workflow file
  • Prefer run: | for any command block longer than one line
  • Quote values that contain colons, braces, or other YAML-sensitive punctuation
  • Run actionlint or another YAML validator before pushing workflow edits