CircleCI "Cannot find a definition for executor named X" error

By Daniel Zoghalchali·Latchkey

A job set executor: X but CircleCI found no executor by that name in the executors block or in an imported orb. The reference is dangling.

What this error means

Config processing fails with "Cannot find a definition for executor named [X]" pointing at the job that references it.

Error: config compilation contained errors:
 * Cannot find a definition for executor named 'node-builder'

Common causes

The executor name is misspelled or undeclared

The job uses a name that does not exist under the top-level executors key, or the typo does not match the declared name.

The executor comes from an orb that is not imported

You referenced an orb executor (like node/default) without listing the orb under orbs.

How to fix it

Declare the executor and match the name

1. Add the executor under the top-level executors key.
2. Reference it with the exact same name in the job.
3. For orb executors, import the orb and use orb-name/executor.

executors:
  node-builder:
    docker:
      - image: cimg/node:20.11
jobs:
  build:
    executor: node-builder
    steps: [checkout, {run: npm test}]

Import the orb that provides it

If the executor is from an orb, declare the orb so the reference resolves.

orbs:
  node: circleci/node@5.2.0
jobs:
  build:
    executor: node/default

How to prevent it

• Keep executor names consistent between declaration and reference.
• Import every orb you reference under orbs.
• Validate config so dangling references fail before merge.

Frequently asked questions

Related guides

References

• GitHub Actions documentation