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

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

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.

Related guides