CircleCI "could not find executor" - Fix References

By Kaveh Alemi·Latchkey

A job references a reusable executor by name, but CircleCI cannot find it - it is not defined under executors:, not imported from the orb, or simply misspelled.

What this error means

Validation fails saying the executor could not be found. The job cannot start because the runtime environment it points to does not resolve.

Could not find executor named "node-builder"
in executors or imported orbs.
Error: config compilation contains errors

Common causes

Executor not defined

The job sets executor: node-builder but there is no executors: { node-builder: ... } block, so the name resolves to nothing.

Orb executor not referenced with its alias

An orb executor must be referenced as <orb-alias>/<executor> with the orb declared. A bare name will not find it.

How to fix it

Define and reference a reusable executor

version: 2.1
executors:
  node-builder:
    docker:
      - image: cimg/node:20.11
    resource_class: medium

jobs:
  test:
    executor: node-builder
    steps: [checkout, { run: npm test }]

Reference an orb executor with its alias

orbs:
  node: circleci/node@5.2.0
jobs:
  test:
    executor: node/default
    steps: [checkout, { run: npm test }]

How to prevent it

• Define reusable executors once and reference them by exact name.
• Import the orb whenever you use an orb-provided executor.
• Validate config so an unresolved executor fails locally.

Frequently asked questions

Related guides

References

• GitHub Actions documentation