{"record":{"id":"0bc0c3aecb26a116","repo":"go-task/task","slug":"matrix-reference-q-must-resolve-to-a-list","errorCode":null,"errorMessage":"matrix reference %q must resolve to a list","messagePattern":"matrix reference %q must resolve to a list","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"variables.go","lineNumber":497,"sourceCode":"\tfor _, row := range matrix.All() {\n\t\tif row.Ref != \"\" {\n\t\t\thasRef = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !hasRef {\n\t\treturn matrix, nil\n\t}\n\tresolved := matrix.DeepCopy()\n\tfor _, row := range resolved.All() {\n\t\tif row.Ref != \"\" {\n\t\t\tv := templater.ResolveRef(row.Ref, cache)\n\t\t\tif cache.Err() != nil {\n\t\t\t\treturn nil, cache.Err()\n\t\t\t}\n\t\t\tvalue, ok := resolvedAsAnySlice(v)\n\t\t\tif !ok {\n\t\t\t\treturn nil, fmt.Errorf(\"matrix reference %q must resolve to a list\", row.Ref)\n\t\t\t}\n\t\t\trow.Value = value\n\t\t}\n\t}\n\treturn resolved, nil\n}\n\nfunc resolveEnumRefs(requires *ast.Requires, cache *templater.Cache) error {\n\tif requires == nil || len(requires.Vars) == 0 {\n\t\treturn nil\n\t}\n\tfor _, v := range requires.Vars {\n\t\tif v.Enum == nil || v.Enum.Ref == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\tresolved := templater.ResolveRef(v.Enum.Ref, cache)\n\t\tif cache.Err() != nil {\n\t\t\treturn cache.Err()","sourceCodeStart":479,"sourceCodeEnd":515,"githubUrl":"https://github.com/go-task/task/blob/385e5ad92af02877b6d7cf9dcc963b5ed916e70a/variables.go#L479-L515","documentation":"resolveMatrixRefs in variables.go resolves `for`-loop matrix references via templater.ResolveRef and expects the result to be a list. If the referenced variable resolves to something that is not a list (scalar, map, empty), the library throws this error because a matrix iteration source must be a list. The reference string is included to point at the offending matrix entry.","triggerScenarios":"A task's `for` loop uses `matrix: [{ref: .VAR}]` (or similar) where VAR is defined as a scalar string/number or a map rather than an array; also occurs when a dynamic variable returns a non-list value.","commonSituations":"Typo pointing the matrix ref at the wrong variable, a dynamic taskfile cmd returning JSON object instead of array, refactor renamed a list variable to a scalar, or YAML quoting turning an intended list into a string.","solutions":["Inspect the referenced variable and change its definition to a list (YAML sequence or JSON array).","If it is a dynamic variable, make the command output a JSON array of values.","Correct the matrix ref in the `for` section so it points at the list variable you intended.","Add a test (like TestResolveMatrixRefsDoesNotMutateInput) or validation step that asserts the variable's type before running."],"exampleFix":"// before\nvars:\n  TARGETS: prod\nfor:\n  matrix: [{ref: .TARGETS}]\n// after\nvars:\n  TARGETS: [dev, prod]\nfor:\n  matrix: [{ref: .TARGETS}]","handlingStrategy":"validation","validationCode":"func mustBeList(name string, v any) error {\n    switch t := v.(type) {\n    case []any:\n        if len(t) == 0 { return fmt.Errorf(\"%s is empty\", name) }\n        return nil\n    default:\n        return fmt.Errorf(\"%s must be a list, got %T\", name, v)\n    }\n}","typeGuard":null,"tryCatchPattern":"values, err := resolveMatrixRefs(...)\nif err != nil {\n    var target any\n    if strings.Contains(err.Error(), \"must resolve to a list\") {\n        return fmt.Errorf(\"check your matrix ref variable type: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep matrix-source variables as YAML sequences only.","For dynamic variables, always emit JSON arrays.","After refactors, grep for matrix refs and re-verify target variable types.","Add a unit test asserting the matrix variable's type."],"tags":["taskfile","matrix","variables","validation"],"backgroundTag":"matrix-reference-not-a-list","analyzedSha":"385e5ad92af02877b6d7cf9dcc963b5ed916e70a","analyzedAt":"2026-09-05T09:01:05.226Z","contentChangedAt":"2026-09-05T09:01:05.226Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}