CircleCI Config "version 2.0 is deprecated" / Wrong Version

By Kaveh Alemi·Latchkey

Your config declares the wrong (or no) top-level version. Orbs, reusable commands, executors, and parameters all require version: 2.1; an older or missing version disables those features or is rejected.

What this error means

Validation fails on the version, or features like orbs:, parameters:, and reusable commands: are rejected as unknown keys because the config is parsed as the older 2.0 schema.

Config version 2.0 does not support orbs.
Set 'version: 2.1' at the top of .circleci/config.yml.
# or
Unsupported config version "3"

Common causes

Missing or wrong top-level version

Without version: 2.1 at the very top, CircleCI may parse the file as 2.0, which has no orbs, parameters, or reusable commands.

An unsupported version number

Only specific versions are valid (2, 2.1). A typo like version: 3 or version: 2.2 is rejected outright.

2.1-only features under a 2.0 config

Using orbs:, parameters:, executors:, or reusable commands: while the file is treated as 2.0 produces "not a valid key" errors.

How to fix it

Declare version 2.1 at the top

version: 2.1

orbs:
  node: circleci/node@5.2.0

jobs:
  build:
    docker: [{ image: cimg/node:20.11 }]
    steps: [checkout, node/install-packages]

Validate after setting the version

Confirm the 2.1 features now resolve.

circleci config validate

How to prevent it

• Always start configs with version: 2.1 to enable modern features.
• Validate config in CI so a wrong version fails on the PR.
• Avoid copying old 2.0 examples without updating the version line.

Frequently asked questions

Related guides

References

• GitHub Actions documentation