CircleCI "executor not found" - Fix Executor References

By Daniel Zoghalchali·Latchkey

A job references a reusable executor by name, but CircleCI cannot find that executor - 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 is invalid

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 imported correctly

For an orb executor you must reference it as <orb-alias>/<executor> and declare the orb. A bare name will not find an orb-provided executor.

Typo or case mismatch

Executor names are exact. Node-Builder will not match node-builder.

How to fix it

Define and reference a reusable executor

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