CircleCI "Cannot find a definition for executor" Error

By Daniel Zoghalchali·Latchkey

A job that uses executor: must name an executor declared under the top-level executors: key or provided by an imported orb. Otherwise CircleCI cannot resolve the execution environment.

What this error means

Config processing fails stating it cannot find a definition for an executor named in a job.

Cannot find a definition for executor named node-builder
in job test. Executors must be declared under the top-level executors key.

Common causes

Executor not declared

The job sets executor: to a name not defined under executors:.

Typo or wrong orb prefix

The name differs from the definition or omits the orb/ prefix.

Orb not imported

An orb-provided executor needs the orb under orbs:.

How to fix it

Declare the executor

Define the executor under the top-level executors key and reference it by name.

executors:
  node-builder:
    docker:
      - image: cimg/node:20.11

jobs:
  test:
    executor: node-builder
    steps:
      - run: npm test

How to prevent it

• Declare every executor under executors:.
• Match executor names exactly, including orb prefixes.
• Import orbs that supply executors you reference.

Frequently asked questions

Related guides

References

• GitHub Actions documentation