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.