GitHub Actions "A mapping was found where a sequence is expected"

By Daniel Zoghalchali·Latchkey

Keys such as steps, on (event list), and a multi-value needs expect a YAML sequence. Writing them as a mapping (key: value pairs) instead of a list of items triggers this structural error.

What this error means

The workflow is invalid at parse time complaining a mapping was found where a sequence was expected, pointing at a list-typed key.

Invalid workflow file: .github/workflows/ci.yml#L10
A mapping was found where a sequence is expected

Common causes

List key written as a mapping

Omitting the leading dashes turns an intended list into a mapping.

Indentation collapsed a list

Misaligned indentation merges list items into a mapping node.

How to fix it

Write the key as a list

1. Add leading dashes to each list item under the key.
2. Confirm indentation is consistent across items.
3. Validate with actionlint or a YAML schema.

steps:
  - uses: actions/checkout@v4
  - run: npm test

How to prevent it

• Run actionlint to catch sequence/mapping mismatches.
• Use editor schema validation for GitHub Actions YAML.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions