CircleCI "config process" Expansion Errors - Debug Orbs & Anchors

The config validates as YAML but circleci config process (the full expansion of orbs, commands, parameters, and anchors) produces an error or unexpected output. The processed config - what CircleCI actually runs - does not match what the source looks like.

What this error means

A config that "looks fine" behaves wrongly because orb commands, reusable commands, or anchors expand into something unexpected. circleci config process either errors during expansion or reveals steps you did not intend.

$ circleci config process .circleci/config.yml
Error: Expansion of command 'node/install-packages' failed:
  parameter 'cache-version' references undefined value

Common causes

A reusable element expands with bad inputs

An orb command or your own command receives a parameter that resolves to nothing during expansion, so the processed config is invalid even though the source parsed.

YAML anchors merge unexpected keys

Anchors/aliases (&x/*x) and merge keys can pull in or override fields in ways that only appear after expansion, producing surprising processed steps.

Parameter substitution not what you expected

A << parameters.* >> or << pipeline.* >> substitution resolves differently than intended, which is visible only in the processed output.

How to fix it

Render and inspect the processed config

Expand everything locally to see exactly what CircleCI will run.

circleci config process .circleci/config.yml > processed.yml
less processed.yml   # inspect the fully-expanded steps

Isolate the failing expansion

1. Comment out orbs/anchors until config process succeeds, then reintroduce them one at a time.
2. Check that every command parameter has a value or default during expansion.
3. Prefer explicit reusable commands over clever anchors when the merge behavior is unclear.

How to prevent it

• Run circleci config process in CI, not just validate, to catch expansion bugs.
• Keep anchors simple; favor reusable commands/executors for shared steps.
• Pin orb versions so expansion output stays stable.

Related guides