CircleCI "Config does not conform to schema"

The YAML parsed, but it does not match CircleCI's config schema. A key is misspelled, misplaced, missing, or the wrong type, so circleci config validate rejects it.

What this error means

circleci config validate (or the UI) reports the config does not conform to schema and lists the offending key or job. Unlike a parse error, the file is valid YAML - it just breaks CircleCI's rules.

Error: config compilation contains errors:
config does not conform to schema. Action failed validation.
  - in job 'build': 'step' is not a valid key; valid keys are: 'steps', 'docker', ...

Common causes

Misspelled or misplaced key

Singular vs plural (step vs steps, command vs commands), or a job-level key under a step, fails. Each position accepts only a fixed vocabulary.

Missing required key

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

Wrong value type

A list-typed key given a scalar, or a string given a map, fails. steps: must be a list of step items, not a single mapping.

How to fix it

Validate and read each violation

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

circleci config validate

Inspect the processed config

When orbs or anchors obscure the structure, render the fully expanded config to see what is validated.

circleci config process .circleci/config.yml

How to prevent it

• Validate config in CI on every PR before merge.
• Use editor schema support for inline key hints.
• Keep jobs small so misplaced keys are obvious.

Related guides