circleci config validate: Check CircleCI Config
circleci config validate parses .circleci/config.yml, resolves orbs, and reports whether the config conforms to the CircleCI schema.
A malformed CircleCI config fails the pipeline on load with a terse message in the UI. Validating with the CLI locally or in a PR gives you the same check with a faster loop.
What it does
circleci config validate reads a config file (default .circleci/config.yml), fetches and resolves any orbs referenced, and validates the result against CircleCI's schema. It reports Config file at .circleci/config.yml is valid. on success.
Common usage
circleci config validate
circleci config validate .circleci/config.yml
circleci config validate --org-id <ORG_ID> # required for orb resolution
circleci config validate -c .circleci/config.ymlOptions
| Flag | What it does |
|---|---|
| [path] | Path to the config file (defaults to .circleci/config.yml) |
| -c, --config <path> | Explicit config file path |
| --org-id <id> | Organization id, needed to resolve private/registry orbs |
| --org-slug <slug> | Organization slug alternative to --org-id |
| --skip-update-check | Do not check for a CLI update first |
In CI
Run circleci config validate in a lint job or pre-commit so config errors are caught in the PR. If you use dynamic config, also run circleci config process (see the process reference) to expand parameters and orbs before validating.
Common errors in CI
Failures print Error: config file is not valid and config compilation contains errors: ... [#/jobs/build] .... Error: Could not find a usable config.yml means the path is wrong. Orb resolution without --org-id can fail with Orb ... not found. circleci: command not found means the CLI is not installed on the runner.