GitLab CI "parallel:matrix config invalid" - Bad Matrix Keys

parallel:matrix takes a list of variable maps, where each value is an array. GitLab expands the cross product into jobs. Scalars where arrays are expected, or too many combinations, fail validation.

What this error means

CI lint reports the parallel:matrix config is invalid, often pointing at a key whose value is a single string rather than a list, or noting the combination count exceeds the limit.

This GitLab CI configuration is invalid:
jobs:test:parallel:matrix config should be an array of hashes

Common causes

Matrix value is a scalar, not an array

Each variable under a matrix entry must be a list, even with one value: PROVIDER: [aws], not PROVIDER: aws.

Too many combinations

The cross product of all arrays must stay within the 200-job limit per matrix; large arrays multiply quickly.

Reserved or duplicate keys

Matrix keys are variable names; reusing a reserved CI variable name or duplicating a key within one entry is rejected.

How to fix it

Wrap each value in an array

Use the array-of-hashes shape with list values so the cross product expands correctly.

test:
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
        VERSION: ['18', '20']

Keep the combination count under the limit

1. Multiply the lengths of all arrays in an entry; keep the product at or below 200.
2. Split large matrices into multiple jobs if needed.
3. Re-validate in the Pipeline Editor after trimming.

How to prevent it

• Always express matrix values as arrays, even single-element ones.
• Budget the cross-product size against the 200-job cap.
• Avoid reusing reserved variable names as matrix keys.

Related guides