{"record":{"id":"271d90e64f1f447c","repo":"hashicorp/terraform","slug":"task-stage-s-s","errorCode":null,"errorMessage":"Task Stage '%s': %s.","messagePattern":"Task Stage '(.+?)': (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend_taskStages.go","lineNumber":45,"sourceCode":"\t\toptions := tfe.TaskStageReadOptions{\n\t\t\tInclude: []tfe.TaskStageIncludeOpt{tfe.TaskStageTaskResults, tfe.PolicyEvaluationsTaskResults},\n\t\t}\n\t\tstage, err := b.client.TaskStages.Read(ctx.StopContext, stageID, &options)\n\t\tif err != nil {\n\t\t\treturn false, generalError(\"Failed to retrieve task stage\", err)\n\t\t}\n\n\t\tswitch stage.Status {\n\t\tcase tfe.TaskStagePending:\n\t\t\t// Waiting for it to start\n\t\t\treturn true, nil\n\t\tcase tfe.TaskStageRunning:\n\t\t\t// not a terminal status so we continue to poll\n\t\t\treturn true, nil\n\t\tcase tfe.TaskStagePassed:\n\t\t\treturn false, nil\n\t\tcase tfe.TaskStageCanceled, tfe.TaskStageErrored, tfe.TaskStageFailed:\n\t\t\treturn false, fmt.Errorf(\"Task Stage '%s': %s.\", stage.ID, stage.Status)\n\t\tcase tfe.TaskStageAwaitingOverride:\n\t\t\treturn false, fmt.Errorf(\"Task Stage '%s' awaiting override.\", stage.ID)\n\t\tcase tfe.TaskStageUnreachable:\n\t\t\treturn false, nil\n\t\tdefault:\n\t\t\treturn false, fmt.Errorf(\"Task stage '%s' has invalid status: %s\", stage.ID, stage.Status)\n\t\t}\n\t})\n}\n","sourceCodeStart":27,"sourceCodeEnd":55,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend_taskStages.go#L27-L55","documentation":"waitTaskStage polls a TFC Task Stage; when its status reaches Canceled, Errored, or Failed the polling stops with this error naming the stage ID and its terminal status. This represents a configured Run Task (custom or built-in) that ran during plan/apply and did not pass.","triggerScenarios":"stage.Status is tfe.TaskStageCanceled, tfe.TaskStageErrored, or tfe.TaskStageFailed: the run task endpoint returned an error, the task was canceled, or its exit/evaluation failed during the stage.","commonSituations":"A mandatory/preventive run task (e.g. policy-as-code, cost estimation, custom webhook task) failed and blocked the run; task integration endpoint (external service) was unreachable; task was manually canceled in the TFC UI.","solutions":["Open the stage ID in the TFC/TFE UI to see the task-result detail and address the root cause.","If the task endpoint is a custom service, verify it is up, returning 200, and within the allowed timeout.","For non-mandatory tasks, switch the enforcement level from 'mandatory' so failures don't block.","Override the stage on the TFC UI if the failure is spurious and policy allows overrides."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Inspect task results at the stage before failing the run\nstage, _ := c.TaskStages.Read(ctx, stageID, opts)\nfor _, r := range stage.TaskResults { if r.Status == \"failed\" { log.Println(r.Message) } }","typeGuard":"func isTerminalTaskFailure(s tfe.TaskStageStatus) bool {\n    switch s {\n    case tfe.TaskStageCanceled, tfe.TaskStageErrored, tfe.TaskStageFailed:\n        return true\n    }\n    return false\n}","tryCatchPattern":"// Stop polling on terminal failure; surface stage ID for UI follow-up\nif isTerminalTaskFailure(stage.Status) {\n    return fmt.Errorf(\"task stage %s ended %s; see TFC UI\", stage.ID, stage.Status)\n}","preventionTips":["Make mandatory run tasks only when failures should block; use advisory otherwise.","Monitor external task endpoints for uptime and timeout budget.","Address root-cause task failures before re-running."],"tags":["terraform","remote-backend","tfe","run-tasks","policy","stage"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}