CircleCI Config Schema Validation Errors - Fix Invalid Keys

The YAML parsed fine, but it does not match CircleCI’s config schema. A key is misspelled, in the wrong place, missing, or the wrong type - so the pipeline is rejected at validation.

What this error means

CircleCI reports the config is invalid and lists specific schema violations, naming the offending key or job. Unlike a YAML parse error, the file is well-formed YAML - it just breaks CircleCI’s rules.

CircleCI UI

Config is invalid:
  - in job 'build': key 'step' is not a valid key; valid keys are:
    'steps', 'docker', 'machine', 'executor', 'resource_class', ...
  - in workflow 'ci': missing required key 'jobs'

Common causes

A misspelled or misplaced key

Singular vs plural (step vs steps, command vs commands), or a job-level key placed under a step, fails validation. The schema only accepts a fixed vocabulary in each position.

A missing required key

Every workflow needs jobs:, every job needs steps: and an executor (docker/machine/macos/executor). Omitting a required key is a hard validation failure.

Wrong value type

A field that must be a list given a scalar (or a string given a map) fails. For example steps: must be a list of step items, not a single mapping.

How to fix it

Validate and read the exact violation

The CLI lists every schema error with the job/workflow path. Fix each named key.

Terminal

circleci config validate

Check the key against the schema

Confirm singular vs plural - it is steps, jobs, workflows, commands.
Make sure executor keys (docker, machine, macos, executor) sit at job level, not under a step.
Give list-typed keys a YAML list (- ...), not a single mapping.

Expand and inspect the processed config

If orbs or anchors obscure the structure, render the fully-expanded config to see what CircleCI actually validates.