CircleCI "when" Condition Invalid Logic

By Daniel Zoghalchali·Latchkey

CircleCI logic statements (and, or, not, equal, matches) gate steps, jobs, or workflows. A malformed structure, wrong nesting, or comparing the wrong values produces an invalid config or a condition that never matches.

What this error means

Config processing fails on a when/unless block, or the gated step/job is unexpectedly always or never run.

Error: when clause in job deploy is invalid.
'equal' expects a list of values to compare, got a mapping.

Common causes

Malformed logic operator

equal expects a list, and/or expect lists of conditions; passing the wrong shape fails.

Comparing an unexpanded parameter

Using a pipeline parameter that resolves to empty makes the comparison false.

Steps where a condition belongs

Putting steps directly under when instead of under a condition plus steps is invalid for step-level when.

How to fix it

Use the correct logic shape

Provide equal a list and nest steps under condition correctly.

steps:
  - when:
      condition:
        equal: [main, << pipeline.git.branch >>]
      steps:
        - run: ./deploy.sh

How to prevent it

• Give equal a list of values to compare.
• Verify pipeline parameters resolve before comparing.
• Nest steps under condition for step-level when.

Frequently asked questions

Related guides

References

• GitHub Actions documentation