CircleCI "Cannot find a definition for command" Error

By Daniel Zoghalchali·Latchkey

A job step that calls a reusable command must reference a command defined under the top-level commands: key or provided by an imported orb. A typo or missing definition fails config validation.

What this error means

Config processing fails stating it cannot find a definition for a command name used in a job step.

Cannot find a definition for command named install-deps
in job build. Commands must be declared under the top-level commands key.

Common causes

Command not declared

The command name is used in steps but never defined under commands:.

Typo or wrong namespace

The step references a slightly different name, or an orb command without the orb/ prefix.

Orb not imported

A command from an orb requires the orb to be listed under orbs:.

How to fix it

Declare the command

Define the reusable command under the top-level commands key and call it exactly.

commands:
  install-deps:
    steps:
      - run: npm ci

jobs:
  build:
    steps:
      - install-deps

How to prevent it

• Declare every reusable command under commands:.
• Match command names exactly, including orb prefixes.
• Validate config locally with the CircleCI CLI before pushing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation