GitHub Actions Matrix include Overriding an Existing Combination Value

A matrix combination ends up with a different value than its base list because an include entry matched it and overrode a key. include can both add fields to and overwrite values within a matching combination.

What this error means

A matrix leg runs with a value you did not set in the base vectors - an include entry that partially matched the combination replaced one of its keys.

matrix:
  node: [18, 20]
  os: [ubuntu-latest]
  include:
    - node: 20
      os: ubuntu-latest
      node: 21        # overrides the matched leg's node value

Common causes

include matched and overwrote a key

When an include entry’s keys match an existing generated combination, its other keys are merged in - and a key that already exists can be overwritten, not just appended.

Order and key overlap are subtle

include is processed against each base combination; an entry meant to add metadata can unexpectedly change a core dimension if it reuses that dimension’s key.

How to fix it

Add only new keys when extending

When you mean to attach metadata to an existing leg, include only the matching keys plus the new field - do not redefine a base dimension.

matrix:
  node: [18, 20]
  os: [ubuntu-latest]
  include:
    - node: 20
      os: ubuntu-latest
      experimental: true   # adds a field, does not change node/os

Verify the expanded matrix

1. Print the matrix context in a debug job to confirm each leg’s final values.
2. Avoid putting a base dimension key inside an include entry unless you intend to override it.
3. Use a brand-new value to add a separate leg instead of mutating an existing one.

How to prevent it

• Keep include entries to matching keys plus genuinely new fields.
• Echo the expanded matrix when tuning include.
• Do not redefine a base matrix dimension inside include unless intended.

Related guides