We have rolled out a new config validator that produces clearer, more actionable error messages. It already runs for most pipelines and surfaces remaining issues as pipeline warnings (also included in Slack and email notifications for pipeline completion).
On Dec 14, 2026, warnings will become hard failures and block pipelines: configs that still trigger them will fail validation and will not start pipelines until fixed.
Please review recent pipelines for config validation warnings and fix them before that date. Agents and local CLI command ‘circleci config validate --next' can help apply the fixes.
What to do now
- Open a recent pipeline in the CircleCI UI and check for config validation warnings.
- Fix the underlying .circleci/config.yml (or orb) issue using the guidance below.
- Re-run the pipeline and confirm the warning is gone.
Common cases to fix
These are the most common remaining classes of issues we see in production (ranked by breadth × volume). Exact wording may vary slightly by location in the config.
- Incorrectly formed step
A step map is indented incorrectly — for example when: on_fail / when: on_success sitting as a sibling of a step, or name / command not nested under run:.
Fix: Nest keys under the step. Use a proper conditional step wrapper for when:.
- Empty requires: — message like
requires has no value
A job lists requires: with no jobs (including null or a fully commented-out list).
Fix: Remove requires:, or list the job names it should wait for.
- Invalid enum default — Invalid enum default value
A parameter default: is not one of the values in enum: (including default: “” when empty string is not listed).
Fix: Set the default to an allowed enum value, or add the value to enum:.
- Templated job type: — Job … type … is not recognised
Using *type: « pipeline.parameters.… » *(or similar) instead of a concrete job type.
Fix: Use a literal type (approval, build, …), or gate the job/workflow with when: instead of templating type:.
- Undeclared job or command argument — does not take an argument named …
Passing a key the job/command does not declare (for example upstream:), or an orb-prefixed argument key.
Fix: Remove the unknown key, or declare it under parameters:.
- Invalid or empty run step — A run step must specify a command
A step name that is not a real command, or a run step missing command:.
Fix: Correct the step/command name, or add command:.
- Both when: and unless: on a workflow — Invalid workflow condition
A workflow sets both keys (a valueless unless: still counts).
Fix: Keep only one of when: or unless:.
- Parameter type mismatch — parameter X must be of type Y
An argument does not match the declared type (integer, enum, boolean, string). Matrix parameters that share a name with a typed argument are a common trap.
Fix: Pass a value of the declared type; rename colliding matrix parameters if needed.
- Empty list-shaped field — Expected a list value
A key that must be a list is present but empty (for example bare docker:).
Fix: Provide a list value, or remove the key.
10.Invalid command name — Invalid command name, must match ^[a-z][a-z0-9_-]*$
Command names with characters outside the allowed pattern (for example a /).
Fix: Rename the command (e.g. ace/validate → ace-validate).
Other less common warnings you may also see include empty cache/workspace paths:, non-positive or non-integer parallelism, and unsupported checkout method values (must be blobless, shallow, or full).
