{"record":{"id":"f9801748f07d1110","repo":"go-task/task","slug":"task-precondition-not-met","errorCode":null,"errorMessage":"task: precondition not met","messagePattern":"task: precondition not met","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"precondition.go","lineNumber":14,"sourceCode":"package task\n\nimport (\n\t\"context\"\n\n\t\"github.com/go-task/task/v3/errors\"\n\t\"github.com/go-task/task/v3/internal/env\"\n\t\"github.com/go-task/task/v3/internal/execext\"\n\t\"github.com/go-task/task/v3/internal/logger\"\n\t\"github.com/go-task/task/v3/taskfile/ast\"\n)\n\n// ErrPreconditionFailed is returned when a precondition fails\nvar ErrPreconditionFailed = errors.New(\"task: precondition not met\")\n\nfunc (e *Executor) areTaskPreconditionsMet(ctx context.Context, t *ast.Task) (bool, error) {\n\tfor _, p := range t.Preconditions {\n\t\terr := execext.RunCommand(ctx, &execext.RunCommandOptions{\n\t\t\tCommand: p.Sh,\n\t\t\tDir:     t.Dir,\n\t\t\tEnv:     env.Get(t),\n\t\t})\n\t\tif err != nil {\n\t\t\tif !errors.Is(err, context.Canceled) {\n\t\t\t\te.Logger.Errf(logger.Magenta, \"task: %s\\n\", p.Msg)\n\t\t\t}\n\t\t\treturn false, ErrPreconditionFailed\n\t\t}\n\t}\n\n\treturn true, nil\n}","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/go-task/task/blob/385e5ad92af02877b6d7cf9dcc963b5ed916e70a/precondition.go#L1-L32","documentation":"ErrPreconditionFailed is returned by Executor.areTaskPreconditionsMet when one of a task's `preconditions` shell commands exits non-zero. Preconditions act as guard clauses: each `sh:` snippet is run before the task's commands, its stderr/output is echoed, and if any check fails the whole task is aborted with this error. Unlike errors in commands, a precondition failure means 'this task should not run at all'.","triggerScenarios":"A task declares `preconditions: [{sh: ...}]` and the shell snippet returns a non-zero exit code, e.g. checking for an env var (`sh: '[ -n \"$API_KEY\" ]'`), a required binary (`command -v docker`), or a service being reachable. Any non-zero status — including the snippet not being parseable — triggers it.","commonSituations":"Missing environment variables or config files on a new machine; required tools (docker, terraform) not installed or not on PATH; prerequisites service not running; running a task outside the expected directory. Frequently seen after cloning a repo and skipping setup docs.","solutions":["Run the precondition's sh snippet manually in your shell to see exactly which check fails and why","Install the missing dependency or set the missing environment variable the check verifies","Ensure the snippet runs with the same interpreter/environment as task (shell availability, PATH, cwd = task dir)","If the precondition is no longer relevant, update or remove it in the Taskfile"],"exampleFix":"# before (fails when var unset)\npreconditions:\n  - sh: test -n \"$API_KEY\"\n# after\npreconditions:\n  - sh: test -n \"$API_KEY\"\n    msg: \"API_KEY must be set; run: export API_KEY=...\"","handlingStrategy":"try-catch","validationCode":"// Before running the task, replicate its preconditions yourself:\nfor _, p := range task.Preconditions {\n    if err := execext.RunCommand(ctx, &execext.RunCommandOptions{Command: p.Sh, Dir: task.Dir}); err != nil {\n        return fmt.Errorf(\"precondition not met: %s\", p.Sh)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := e.Run(ctx, task, call); err != nil {\n    if errors.Is(err, precondition.ErrPreconditionFailed) {\n        log.Printf(\"skipping %s: preconditions unmet\", task.Name)\n        return nil // or surface a clear user-facing message\n    }\n    return err\n}","preventionTips":["Run each precondition `sh:` snippet manually in the target environment before invoking the task","Give every precondition a `msg:` so failures explain themselves","Keep precondition checks to simple, dependency-free shell tests (test -n, command -v, test -f)","Document required env vars/tools in the repo README so new machines satisfy preconditions"],"tags":["go-task","precondition","taskfile","shell","guard-clause"],"backgroundTag":"precondition-check-failed","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"}