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

By Daniel Zoghalchali·Latchkey

A step invoked a named command that CircleCI cannot resolve. The command is not defined under the top-level commands key, or it belongs to an orb you did not import.

What this error means

Config processing fails with "Cannot find a definition for command named [X]" at the step that calls it.

Error: config compilation contained errors:
 * Cannot find a definition for command named 'install-deps'

Common causes

The command is not declared

A step references install-deps but no commands.install-deps exists, or the name is misspelled.

The command is from an unimported orb

You called an orb command without prefixing it with the orb name or without importing the orb.

How to fix it

Define the reusable command

1. Add the command under the top-level commands key.
2. Reference it by the exact name in the step.
3. For orb commands, use orb-name/command.

commands:
  install-deps:
    steps:
      - run: npm ci
jobs:
  test:
    docker: [{image: cimg/node:20.11}]
    steps:
      - checkout
      - install-deps

Import and namespace the orb command

Declare the orb and call its command with the orb prefix.

orbs:
  node: circleci/node@5.2.0
# then call: node/install-packages

How to prevent it

• Declare every reusable command before referencing it.
• Namespace orb commands with the orb name.
• Validate config so undefined command references fail early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation