CircleCI when/unless Conditions Not Working - Fix Logic

A when/unless condition is not gating the workflow the way you expect - it always runs, never runs, or fails validation. The condition is not evaluating to a real boolean, or it is placed at a level where it has no effect.

What this error means

A workflow runs regardless of the parameter you meant to gate on, or validation rejects the condition. The job either always fires or never does, because the when expression does not resolve to a true/false the way you intended.

Config is invalid:
  - workflow 'deploy': 'when' expects a boolean or a logic statement,
    got string "<< pipeline.parameters.do_deploy >>"

Common causes

Condition is a string, not a boolean

A when on a string-typed parameter is truthy whenever the string is non-empty. To gate on true/false you need a boolean parameter or an explicit equal/and/or logic statement.

when placed at the wrong level

Workflow-level when gates the whole workflow; a per-job when (under the workflow’s job entry) gates that job. Putting it in the wrong place means it does not filter what you intended.

Logic operators misused

Compound conditions need the and/or/not/equal logic syntax. Writing a bare expression or comparing mismatched types does not evaluate as expected.

How to fix it

Gate on a boolean parameter or a logic statement

parameters:
  do_deploy:
    type: boolean
    default: false

workflows:
  deploy:
    when: << pipeline.parameters.do_deploy >>
    jobs:
      - deploy

  release:
    when:
      and:
        - equal: [main, << pipeline.git.branch >>]
        - << pipeline.parameters.do_deploy >>
    jobs:
      - publish

Use the right level and operators

1. Use a workflow-level when to skip an entire workflow.
2. Use a per-job when under the workflow job to skip one job.
3. Wrap multiple checks in and/or, and use equal: [a, b] for comparisons.

How to prevent it

• Gate on boolean parameters, not strings, for clear true/false logic.
• Use and/or/not/equal for compound conditions.
• Place when at the workflow or job level deliberately.

Related guides