What causes "enum reference %q must resolve to a list" in go-task/task?

Change the referenced variable to a list of strings (YAML sequence).

enum reference %q must resolve to a list

Error message

enum reference %q must resolve to a list

What it means

resolveEnumRefs in variables.go resolves a prompt variable's `enum` reference via templater.ResolveRef and requires the resolved value to be a list. When the referenced variable does not resolve to a list, the library throws this error because interactive prompt choices must come from an array of options.

Source

Thrown at variables.go:519

	}
	return resolved, nil
}

func resolveEnumRefs(requires *ast.Requires, cache *templater.Cache) error {
	if requires == nil || len(requires.Vars) == 0 {
		return nil
	}
	for _, v := range requires.Vars {
		if v.Enum == nil || v.Enum.Ref == "" {
			continue
		}
		resolved := templater.ResolveRef(v.Enum.Ref, cache)
		if cache.Err() != nil {
			return cache.Err()
		}
		arr, ok := resolvedAsAnySlice(resolved)
		if !ok {
			return fmt.Errorf("enum reference %q must resolve to a list", v.Enum.Ref)
		}
		strValues := make([]string, 0, len(arr))
		for _, item := range arr {
			s, ok := item.(string)
			if !ok {
				return fmt.Errorf("enum reference %q must contain only strings", v.Enum.Ref)
			}
			strValues = append(strValues, s)
		}
		v.Enum.Value = strValues
	}
	return nil
}

// product generates the cartesian product of the input map of slices.
func product(matrix *ast.Matrix) []map[string]any {
	if matrix.Len() == 0 {
		return nil

View on GitHub (pinned to 385e5ad92a)

Solutions

Change the referenced variable to a list of strings (YAML sequence).
If dynamic, output a JSON array from the command.
Fix the enum ref to point at the correct list variable.
Guard with a pre-run check that the variable is a list before invoking prompts.

Example fix

// before
vars:
  ENV: production
prompt:
  enum:
    ref: .ENV
// after
vars:
  ENV: [dev, staging, production]
prompt:
  enum:
    ref: .ENV

Defensive patterns

Strategy: validation

Validate before calling

func enumSourceIsValid(v any) bool {
    _, ok := v.([]any)
    return ok
}

Type guard

func isStringList(v any) bool {
    arr, ok := v.([]any)
    if !ok { return false }
    for _, item := range arr {
        if _, ok := item.(string); !ok { return false }
    }
    return true
}

Try / catch

task, err := compiledTask(...)
if err != nil {
    if strings.Contains(err.Error(), "enum reference") {
        return fmt.Errorf("prompt enum must point at a list of strings: %w", err)
    }
    return err
}

Prevention

Point enum refs only at variables declared as YAML sequences.
Ensure dynamic variables emit JSON arrays of strings.
Validate prompt variable sources before interactive runs.
Keep one canonical list variable per enum and avoid retyping it.

When it happens

Trigger: Declaring a variable with an enum `ref:` (e.g. for prompt variables used by resolveEnumRefForPrompt or compiledTask) where the referenced variable is a scalar, map, or empty value instead of a list.

Common situations: Enum ref pointing at a string by mistake, dynamic variable emitting a single JSON value rather than an array, or a rename that changed the variable's type from list to scalar.

Related errors

AI-assisted analysis of go-task/task@385e5ad92a (2026-09-05). Data as JSON: /api/errors/ed981985e0048d2b. Report an issue: GitHub.