GitLab CI "retry" Errors - Invalid retry:when or Out-of-Range max

retry automatically re-runs a failed job. The config is rejected when retry:max is outside the allowed 0–2 range, or when retry:when lists a failure reason GitLab does not recognize.

What this error means

Validation fails naming the retry config: a max greater than 2, or a when value that is not a known failure reason. The job logic is fine - only the retry block is invalid.

Pipeline Editor

This GitLab CI configuration is invalid:
jobs:test:retry:max config must be less than or equal to 2

Common causes

retry:max out of range

retry:max accepts 0, 1, or 2. A higher number (or a negative) is rejected by the schema.

Unknown retry:when reason

retry:when must use recognized reasons (e.g. runner_system_failure, stuck_or_timeout_failure, script_failure, api_failure). A typo or invented value fails validation.

How to fix it

Use a valid max and known reasons

Scope retries to transient infrastructure failures so genuine script failures are not silently re-run.

.gitlab-ci.yml

test:
  script: make test
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

Validate retry reasons against the schema

Keep retry:max within 0–2.
Use only documented retry:when failure reasons.
Re-validate in the Pipeline Editor after editing the retry block.

How to prevent it

Cap retry:max at 2 and scope when to transient reasons.
Avoid retrying script_failure so real failures surface.
Validate retry config in the editor before merging.