Introduction

Matrix workflows fail before execution when GitHub cannot evaluate the strategy.matrix block into valid job permutations. The cause is often a small YAML or expression mistake: wrong indentation, malformed include entries, or use of matrix.* in a place where that context does not exist yet. Because the workflow never starts, the error feels abstract even though the fix is usually very local.

Symptoms

  • GitHub marks the workflow as invalid before any matrix job starts
  • Errors reference strategy, matrix, or unexpected values in the workflow
  • The workflow broke after adding include, exclude, or another dimension
  • Expressions using matrix.* fail outside the step or job context

Common Causes

  • The strategy block is indented at the wrong level
  • include or exclude entries do not match the matrix structure correctly
  • Matrix variables are referenced outside the job or step context where they exist
  • YAML list and mapping syntax is mixed incorrectly in the matrix definition

Step-by-Step Fix

  1. 1.**Validate the YAML structure around strategy.matrix**
  2. 2.The matrix block must live inside the job definition, not at the workflow root or another invalid level.
yaml
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [18, 20]
  1. 1.**Review include and exclude entries carefully**
  2. 2.They must describe coherent matrix combinations rather than partial or malformed objects that break the matrix evaluation.
  3. 3.Use matrix variables only where they are actually available
  4. 4.matrix.* cannot be referenced at the workflow root and is not available before the matrix job is created.
  5. 5.Retest with a minimal matrix if needed
  6. 6.If the expanded matrix is complex, strip it back to one dimension, validate, then reintroduce each dimension or include rule one at a time.

Prevention

  • Keep matrix definitions compact and readable instead of embedding too much logic
  • Test complex include and exclude changes in small increments
  • Avoid using matrix.* outside the job and step scopes that support it
  • Run workflow linting before pushing matrix refactors