GitLab CI parallel/matrix Errors - Invalid parallel or matrix Config

By Daniel Zoghalchali·Latchkey

parallel splits a job into N copies, and parallel:matrix fans it out across variable combinations. The config fails when the count is out of range or the matrix shape is wrong.

What this error means

Validation rejects the job: parallel must be between 1 and 200, a matrix entry is not a list of mappings, or the expanded matrix exceeds the allowed number of jobs.

This GitLab CI configuration is invalid:
jobs:test:parallel config must be greater than or equal to 1 and less than or equal to 200

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

Common causes

parallel count out of range

parallel must be an integer from 1 to 200. A 0, a negative, or a value from an unresolved variable fails validation.

Malformed matrix variables

parallel:matrix expects a list of mappings of variable → list of values. A scalar where a list is expected, or a single mapping not wrapped in a list, is invalid.

How to fix it

Use a valid parallel count

test:
  script: make test
  parallel: 5   # 1..200

Shape the matrix correctly

Each list item is a mapping; each value is a list. The product of all lists is the number of jobs and must stay within the limit.

test:
  script: ./run.sh
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
        REGION: [us-east-1, eu-west-1]

How to prevent it

• Validate matrix shape in the Pipeline Editor before pushing.
• Keep matrix products small to stay within concurrency and limits.
• Avoid driving parallel from variables that may be empty.

Frequently asked questions

Related guides

References

• GitHub Actions documentation