hashicorp/terraform · error

Task Stage '%s': %s.

Error message

Task Stage '%s': %s.

What it means

Emitted by waitTaskStage (backend_taskStages.go:44-45) when a polled TaskStage reaches a terminal failure status — Canceled, Errored, or Failed. Task stages represent run tasks (Sentinel policy evaluations, custom run tasks) attached to a run stage; this error reports the stage ID and the failing status so the caller knows the run was blocked by a task that did not pass.

Source

Thrown at internal/backend/remote/backend_taskStages.go:45

		options := tfe.TaskStageReadOptions{
			Include: []tfe.TaskStageIncludeOpt{tfe.TaskStageTaskResults, tfe.PolicyEvaluationsTaskResults},
		}
		stage, err := b.client.TaskStages.Read(ctx.StopContext, stageID, &options)
		if err != nil {
			return false, generalError("Failed to retrieve task stage", err)
		}

		switch stage.Status {
		case tfe.TaskStagePending:
			// Waiting for it to start
			return true, nil
		case tfe.TaskStageRunning:
			// not a terminal status so we continue to poll
			return true, nil
		case tfe.TaskStagePassed:
			return false, nil
		case tfe.TaskStageCanceled, tfe.TaskStageErrored, tfe.TaskStageFailed:
			return false, fmt.Errorf("Task Stage '%s': %s.", stage.ID, stage.Status)
		case tfe.TaskStageAwaitingOverride:
			return false, fmt.Errorf("Task Stage '%s' awaiting override.", stage.ID)
		case tfe.TaskStageUnreachable:
			return false, nil
		default:
			return false, fmt.Errorf("Task stage '%s' has invalid status: %s", stage.ID, stage.Status)
		}
	})
}

View on GitHub (pinned to c9def3e214)

Solutions

  1. Open the run in the TFC/TFE UI and inspect the task results to see the exact policy/task failure reason.
  2. Fix the configuration so it satisfies the policy (e.g. approved region, required tags), then re-run.
  3. If the policy is configured as advisory/overridable and the failure is Canceled/Errored (not Failed), check task-runner health and retry.
  4. Coordinate with the workspace admin to adjust policy enforcement only if the rejection is unintended.

Example fix

// before: plan blocked by policy
Error: Task Stage 'taskstage-xxx': failed.

// after: review policy results in UI, fix config to comply, re-run
$ terraform plan   # config now satisfies Sentinel policy
Defensive patterns

Strategy: try-catch

Validate before calling

// Preflight: list task stages/run tasks on the workspace to anticipate failures.
ws, _ := r.client.Workspaces.Read(ctx, r.organization, r.workspace.Name)
if len(ws.TaskStagesIDs()) > 0 { /* warn that run tasks are active */ }

Try / catch

// Differentiate terminal task failure from override-pending for the operator.
switch stage.Status {
case tfe.TaskStageCanceled, tfe.TaskStageErrored, tfe.TaskStageFailed:
    return fmt.Errorf("Task Stage '%s': %s.", stage.ID, stage.Status)
case tfe.TaskStageAwaitingOverride:
    return fmt.Errorf("Task Stage '%s' awaiting override.", stage.ID)
}

Prevention

When it happens

Trigger: A run task attached to the plan/apply stage fails: a Sentinel policy set enforces a hard failure, a custom task returns an error, or the task execution is canceled (e.g. by an admin or a timeout). The polling loop in waitTaskStage observes the status and returns this error.

Common situations: Sentinel policy enforcement rejecting the plan (e.g. forbid specific resource types/regions); a custom run-task endpoint returning an error; task runner infrastructure issue causing Errored status; admin canceled the task stage.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/271d90e64f1f447c. Report an issue: GitHub.