hashicorp/terraform · error

Task stage '%s' has invalid status: %s

Error message

Task stage '%s' has invalid status: %s

What it means

Emitted by waitTaskStage (backend_taskStages.go:50-51) in the switch default branch when the API returns a TaskStage.Status value not covered by the enumerated cases (pending, running, passed, canceled, errored, failed, awaiting_override, unreachable). This indicates the client and server disagree on the set of possible statuses — typically an API version skew.

Source

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

		}

		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. Upgrade the Terraform CLI (and its go-tfe dependency) to a version that knows the new status.
2. Downgrade/align the TFE server to a version whose statuses this client recognizes.
3. Report the unrecognized status string to confirm whether it is a legitimate new value or a corrupted response.
4. Retry against a matched client/server pair to confirm the skew hypothesis.

Example fix

// before
Error: Task stage 'taskstage-xxx' has invalid status: queued

// after: upgrade CLI to match server
$ terraform version  # upgrade to release supporting 'queued' status

// Validate the status against the known set; log unknowns explicitly for version-skew triage.
known := map[tfe.TaskStageStatus]bool{
    tfe.TaskStagePending:true, tfe.TaskStageRunning:true, tfe.TaskStagePassed:true,
    tfe.TaskStageCanceled:true, tfe.TaskStageErrored:true, tfe.TaskStageFailed:true,
    tfe.TaskStageAwaitingOverride:true, tfe.TaskStageUnreachable:true,
}
if !known[stage.Status] {
    return fmt.Errorf("unrecognized task stage status %q; client/server version skew", stage.Status)
}

When it happens

Trigger: A newer TFC/TFE server returns a task-stage status that this build of go-tfe/terraform does not recognize (e.g. a newly introduced status like 'paused' or 'skipped'), so none of the cases match and the default reports the raw status string.

Common situations: Client/server version mismatch: Terraform CLI built against an older go-tfe than the deployed TFE; a beta feature introducing a new status; server-side rollout of a new task lifecycle ahead of client support.

Related errors

• remote backend doesn't support %s
• {joined API error payload}
• {r.Status}
• ErrPluginNotSupported
• expected on 1 response value, got: %d

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