go-task/task · error

task: invalid run "%s"

Error message

task: invalid run "%s"

What it means

Task validates the `run:` attribute of a task against its known execution modes (e.g. always, once, when_changed) inside GetHash, which maps the mode to a hashing strategy. An unrecognized value aborts with this error before the task runs. It is a strict enum-validation error for the Taskfile's `run` field.

Source

Thrown at hash.go:22

	"cmp"
	"fmt"

	"github.com/go-task/task/v3/internal/hash"
	"github.com/go-task/task/v3/taskfile/ast"
)

func (e *Executor) GetHash(t *ast.Task) (string, error) {
	r := cmp.Or(t.Run, e.Taskfile.Run)
	var h hash.HashFunc
	switch r {
	case "always":
		h = hash.Empty
	case "once":
		h = hash.Name
	case "when_changed":
		h = hash.Hash
	default:
		return "", fmt.Errorf(`task: invalid run "%s"`, r)
	}
	return h(t)
}

View on GitHub (pinned to 385e5ad92a)

Solutions

1. Set `run:` to a supported value: always, once, or when_changed
2. Check the Taskfile schema/docs for your Task version — older versions support fewer modes
3. Validate the Taskfile with `task --list` or the JSON schema in your editor to catch typos

Example fix

# before
mytask:
  run: onc
  cmds: [echo hi]
# after
mytask:
  run: once
  cmds: [echo hi]

var validRunModes = map[string]bool{"always":true,"once":true,"when_changed":true}
if r := taskDef.Run; r != "" && !validRunModes[r] {
  return fmt.Errorf("invalid run mode %q in task %s", r, taskDef.Name)
}

err := t.Run(ctx)
if err != nil && strings.HasPrefix(err.Error(), `task: invalid run`) {
  // fix or strip the run: attribute before retrying
}

When it happens

Trigger: A task declares `run: <value>` with a string that is not one of the supported modes, and startExecution calls GetHash to pick the status-hash strategy.

Common situations: Typo like `run: onc` or `run: once_per_taskfile`, copying modes from other tools (e.g. `run: always` misspelled as `run: alway`), or YAML quoting issues leaving an unexpected value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• task: Included Taskfiles can't have dotenv declarations. Ple
• loop var must be a delimiter-separated string, list or a map
• task: %w "%s"
• task: output style %q not recognized
• task: output style %q does not support the group begin/end p

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