{"record":{"id":"b8f9bde024cc0dee","repo":"nektos/act","slug":"the-workflow-is-not-valid-matrix-exclude-key-q-d","errorCode":null,"errorMessage":"the workflow is not valid. Matrix exclude key %q does not match any key within the matrix","messagePattern":"the workflow is not valid\\. Matrix exclude key %q does not match any key within the matrix","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/model/workflow.go","lineNumber":432,"sourceCode":"\t\t\t\t\t\ti := i.(map[string]interface{})\n\t\t\t\t\t\tincludes = append(includes, i)\n\t\t\t\t\t}\n\t\t\t\tcase interface{}:\n\t\t\t\t\tv := v.(map[string]interface{})\n\t\t\t\t\tincludes = append(includes, v)\n\t\t\t\t}\n\t\t\t}\n\t\t\tdelete(m, \"include\")\n\n\t\t\texcludes := make([]map[string]interface{}, 0)\n\t\t\tfor _, e := range m[\"exclude\"] {\n\t\t\t\te := e.(map[string]interface{})\n\t\t\t\tfor k := range e {\n\t\t\t\t\tif _, ok := m[k]; ok {\n\t\t\t\t\t\texcludes = append(excludes, e)\n\t\t\t\t\t} else {\n\t\t\t\t\t\t// We fail completely here because that's what GitHub does for non-existing matrix keys, fail on exclude, silent skip on include\n\t\t\t\t\t\treturn nil, fmt.Errorf(\"the workflow is not valid. Matrix exclude key %q does not match any key within the matrix\", k)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tdelete(m, \"exclude\")\n\n\t\t\tmatrixProduct := common.CartesianProduct(m)\n\t\tMATRIX:\n\t\t\tfor _, matrix := range matrixProduct {\n\t\t\t\tfor _, exclude := range excludes {\n\t\t\t\t\tif commonKeysMatch(matrix, exclude) {\n\t\t\t\t\t\tlog.Debugf(\"Skipping matrix '%v' due to exclude '%v'\", matrix, exclude)\n\t\t\t\t\t\tcontinue MATRIX\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tmatrixes = append(matrixes, matrix)\n\t\t\t}\n\t\t\tfor _, include := range includes {\n\t\t\t\tmatched := false","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/nektos/act/blob/4f411281417e88660bea1c1a1749aa71ae0bd60f/pkg/model/workflow.go#L414-L450","documentation":"During matrix expansion, act verifies every key used in a `matrix.exclude` entry exists as a top-level matrix key. GitHub fails hard on exclude entries referencing undefined matrix keys (but silently skips non-matching include entries), and act replicates that behavior by returning this error.","triggerScenarios":"A matrix defines os: [ubuntu-latest] and node: [20], but an exclude entry uses `{ os: windows-latest, foo: bar }` — key `foo` is not a matrix key, so expansion aborts. Also triggered by typos in exclude keys (`noded` instead of `node`).","commonSituations":"Copying exclude blocks from another workflow whose matrix has different keys; renaming a matrix dimension without updating excludes; excluding on a value that was moved into an include-generated dimension.","solutions":["Align every key in each exclude entry with the matrix's top-level dimensions.","Fix typos in exclude key names to match matrix keys exactly (case-sensitive).","For value-based exclusions, ensure the value belongs to the defined matrix array — the key must exist even if the value combination never occurs (GitHub then simply skips it)."],"exampleFix":"# before\nmatrix:\n  os: [ubuntu-latest, macos-latest]\n  node: [18, 20]\n  exclude:\n    - os: macos-latest\n      env: prod   # 'env' is not a matrix key\n# after\nmatrix:\n  os: [ubuntu-latest, macos-latest]\n  node: [18, 20]\n  exclude:\n    - os: macos-latest\n      node: 18","handlingStrategy":"validation","validationCode":"func validateExcludeKeys(matrix map[string]interface{}) error {\n    for _, e := range toSlice(matrix[\"exclude\"]) {\n        m, ok := e.(map[string]interface{})\n        if !ok { continue }\n        for k := range m {\n            if _, ok := matrix[k]; !ok {\n                return fmt.Errorf(\"exclude key %q not in matrix\", k)\n            }\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Every key in an exclude entry must be a top-level matrix dimension — no extras.","Rename matrix dimensions and exclude keys together in one commit.","Copy-paste exclude blocks only after checking the source matrix keys."],"tags":["workflow","matrix","exclude","validation"],"backgroundTag":null,"analyzedSha":"4f411281417e88660bea1c1a1749aa71ae0bd60f","analyzedAt":"2026-08-15T09:19:46.307Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}