GitHub Actions "Unexpected value 'X'" - Wrong Scalar in a Mapping Key

The YAML parsed, but a key received a plain scalar where the schema expects a mapping or list - for example a value on a key that should have children, or a list item that should be an object.

What this error means

The workflow is invalid with "Unexpected value 'X'", naming the unexpected scalar. The structure is valid YAML but does not match the Actions schema at that point.

Invalid workflow file: .github/workflows/ci.yml#L8
Unexpected value 'ubuntu-latest'

Common causes

Scalar where a mapping/list is expected

Keys like strategy, jobs, or steps expect a mapping or list of objects. Giving them a bare string yields "Unexpected value".

Value on a key that takes children

Attaching an inline value to a key that should only hold nested keys (for example steps: build) places a scalar where the schema wants a list.

How to fix it

Match the expected shape

Supply a mapping or list where the schema requires one, not a scalar.

jobs:
  build:
    runs-on: ubuntu-latest   # scalar is correct here
    steps:                   # list of objects, not a scalar
      - run: make

Locate the offending key

1. Open the named line and check whether that key expects a value, a mapping, or a list.
2. Convert a stray scalar into the correct nested structure.
3. Run actionlint, which reports the expected type for the key.

How to prevent it

• Copy structure from a known-good workflow rather than from memory.
• Remember which keys take scalars vs mappings vs lists.
• Validate with actionlint to catch shape mismatches early.

Related guides