GitHub Actions "Unexpected value" / "did not expect" Mapping Errors

The YAML parsed, but it does not match the workflow schema. A key is misspelled, in the wrong place, or you supplied a scalar where Actions expects a mapping or list.

What this error means

The workflow is rejected with a message like "Unexpected value <name>" or "did not expect ...", naming the offending key. The file is valid YAML but invalid as a GitHub Actions workflow.

Actions annotation

Invalid workflow file: .github/workflows/ci.yml#L9
Unexpected value 'step' (did you mean 'steps'?)

Common causes

Misspelled or unsupported key

Keys like steps, runs-on, needs, and timeout-minutes are exact. A typo such as step or run-on is not recognized by the schema.

A value placed at the wrong nesting level

Putting a step-level key (like run) directly under a job, or a job-level key under steps, produces an "unexpected value" because the schema expects something else there.

How to fix it

Match keys to the workflow schema exactly

Compare each key against the documented workflow syntax and fix spelling and placement.

.github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Let actionlint pinpoint the bad key

actionlint validates against the real Actions schema and suggests the intended key name.

Terminal

actionlint .github/workflows/ci.yml

How to prevent it

Run actionlint to catch unknown or misplaced keys before merge.
Copy job and step structure from a known-good workflow rather than from memory.
Use an editor with the GitHub Actions YAML schema enabled.