CircleCI Matrix Jobs "duplicate job name" - Fix Matrix Aliases

A matrix job is generating colliding names, or downstream requires: cannot find the matrix-generated jobs. Matrix jobs expand into one job per combination with generated names, and dependencies must reference those, not the base job.

What this error means

Validation fails with duplicate job names, or a requires: cannot resolve the matrix jobs. The fan-out either collides on names or leaves dependents unable to find the per-combination jobs the matrix created.

Config is invalid:
  - workflow 'ci': two jobs named 'test' (from matrix expansion)
  - job 'deploy' requires 'test', but matrix generated
    'test-3.10', 'test-3.11', 'test-3.12'

Common causes

Matrix expands to colliding names

Without a distinguishing name or alias, two matrix invocations of the same job in one workflow can generate the same name and collide.

requires references the base job, not the alias

Matrix jobs get generated names (job-<value>) or a single alias. A requires: on the bare base name does not match the expanded jobs.

Matrix parameters not declared on the job

Every key in matrix.parameters must be a declared parameters: on the job. An undeclared matrix key fails to expand.

How to fix it

Declare parameters and use an alias for dependencies

jobs:
  test:
    parameters:
      pyver: { type: string }
    docker: [{ image: cimg/python:<< parameters.pyver >> }]
    steps: [checkout, { run: pytest }]

workflows:
  ci:
    jobs:
      - test:
          name: test-<< matrix.pyver >>
          matrix:
            parameters:
              pyver: ["3.10", "3.11", "3.12"]
      - deploy:
          requires:
            - test   # the matrix alias gathers all expansions

Give matrix jobs a stable alias to require

1. Set alias: (or a templated name:) so the expansions are addressable.
2. Reference that alias in downstream requires: to depend on the whole matrix.
3. Declare every matrix parameter under the job’s parameters:.

How to prevent it

• Use a templated name: with << matrix.* >> to keep generated names unique.
• Depend on the matrix alias, not the base job name.
• Declare all matrix parameters on the job before expanding.

Related guides