CircleCI "Cannot find a definition for ... orb" - Fix

By Kaveh Alemi·Latchkey

Your config references an orb command, job, or executor that CircleCI cannot resolve. Either the orb is not declared, the element name is wrong, or you used a different alias than you imported.

What this error means

Validation fails saying it cannot find a definition for the referenced orb element. The pipeline never starts because the step you call does not exist under the orb name you used.

Cannot find a definition for command named "install-packages"
in orb or current context. Valid commands are: ...
Error: Config is invalid

Common causes

The orb is not declared

You called node/install-packages but never added the node orb under the top-level orbs: key, so the alias resolves to nothing.

Wrong element name or alias

The orb does not expose a command/job by that name, or you imported it under a different alias than the one you referenced (orbs: { n: circleci/node@5 } then calling node/...).

Calling a command as a job (or vice versa)

Orb elements are typed - a command is used inside steps:, a job is referenced under a workflow. Using one where the other is expected fails to resolve.

How to fix it

Declare the orb and use the matching alias

orbs:
  node: circleci/node@5.2.0

jobs:
  build:
    docker: [{ image: cimg/node:20.11 }]
    steps:
      - checkout
      - node/install-packages

List what the orb actually exposes

Inspect the orb to see its real command, job, and executor names.

circleci orb info circleci/node
circleci orb source circleci/node@5.2.0

Match the element type to where you call it

1. Use orb commands inside a job’s steps: list.
2. Reference orb jobs under a workflow’s jobs: list.
3. Reference orb executors via a job’s executor: key.

How to prevent it

• Pin orbs with an explicit version and keep the alias consistent.
• Run circleci config validate so missing orb elements fail locally.
• Check circleci orb source before adopting an unfamiliar orb element.

Frequently asked questions

Related guides

References

• GitHub Actions documentation