CircleCI "matrix parameters must be declared" Error
A workflow matrix expands a job across parameter combinations. Each key under matrix.parameters must correspond to a parameter declared on the job; undeclared keys cannot be injected.
What this error means
Config processing fails stating that matrix parameters must be declared on the job, naming the offending key.
circleci
In workflow build, matrix parameters must be declared on job test.
Parameter version is used in matrix but not declared under test.parameters.Common causes
Matrix key not declared on the job
The matrix supplies a parameter the job never declared.
Type mismatch
Matrix values must match the declared parameter type.
How to fix it
Declare the matrix parameters on the job
Add each matrix key under the job parameters with the correct type.
.circleci/config.yml
jobs:
test:
parameters:
version:
type: string
docker:
- image: cimg/node:<< parameters.version >>
steps:
- run: npm test
workflows:
build:
jobs:
- test:
matrix:
parameters:
version: ['18.20', '20.11']How to prevent it
- Declare every matrix parameter on the target job.
- Keep matrix value types consistent with declarations.
- Validate matrix workflows with the CircleCI CLI.
Frequently asked questions
What causes ""matrix params" undeclared"?
The matrix supplies a parameter the job never declared.
How do I fix "matrix params" undeclared?
Add each matrix key under the job parameters with the correct type.
Related guides
CircleCI "parameter X is not declared" ErrorFix CircleCI parameter X is not declared - a job, command, or executor uses a parameter that was never declar…
CircleCI "when" Condition Invalid LogicFix CircleCI when/unless logic errors - malformed and/or/not/equal blocks, comparing against an unexpanded pa…
CircleCI "Cannot find a definition for executor" ErrorFix CircleCI cannot find a definition for executor X - the job references an executor that is undefined, miss…