GitHub Actions matrix include adds an undeclared key

Matrix include rules are subtle: an include object whose keys do not match any base matrix vector adds a brand-new combination rather than augmenting existing ones. This yields unexpected extra jobs or jobs missing values you assumed include would supply.

What this error means

The matrix expands to more or fewer jobs than expected, and some jobs lack a value you intended include to set.

# Expected 3 jobs, got 4 - the include created a standalone combination
matrix:
  node: ['18', '20', '22']
  include:
    - os: macos-latest   # undeclared key adds a new job instead of extending

Common causes

Include keys do not match base vectors

An include with only new keys cannot attach to existing combinations, so it becomes its own job.

Misunderstanding include extend vs add semantics

Include extends a combination only when its non-new keys match an existing combination; otherwise it adds one.

How to fix it

Match include keys to the target combinations

1. To extend a combination, give the include the matching base key plus the new value.
2. To add a standalone job, accept that all-new keys create a new combination.
3. Re-run and verify the job count.

matrix:
  node: ['18', '20', '22']
  include:
    - node: '22'
      experimental: true

How to prevent it

• Remember: include extends only when its existing keys match a combination.
• Print the resolved matrix in a debug job when include behavior is unclear.

Related guides