hashicorp/nomad · error

can't unblock terminal deployment

Error message

can't unblock terminal deployment

What it means

Sentinel ErrDeploymentTerminalNoUnblock: UnblockDeployment was called on a deployment that already reached a terminal state; only deployments blocked awaiting unblocking (e.g. auto-revert decisions) can be unblocked.

Source

Thrown at nomad/structs/errors.go:83

	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

	ErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)
	ErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)
	ErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)
	ErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)
	ErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)
	ErrDeploymentTerminalNoUnblock   = errors.New(errDeploymentTerminalNoUnblock)
	ErrDeploymentTerminalNoRun       = errors.New(errDeploymentTerminalNoRun)
	ErrDeploymentTerminalNoSetHealth = errors.New(errDeploymentTerminalNoSetHealth)
	ErrDeploymentRunningNoUnblock    = errors.New(errDeploymentRunningNoUnblock)

	ErrCSIClientRPCIgnorable  = errors.New("CSI client error (ignorable)")
	ErrCSIClientRPCRetryable  = errors.New("CSI client error (retryable)")
	ErrCSIVolumeMaxClaims     = errors.New("volume max claims reached")
	ErrCSIVolumeUnschedulable = errors.New("volume is currently unschedulable")
	ErrCSIPluginInUse         = errors.New("plugin in use")
)

// IsErrNoLeader returns whether the error is due to there being no leader.
func IsErrNoLeader(err error) bool {
	return err != nil && strings.Contains(err.Error(), errNoLeader)
}

// IsErrNoRegionPath returns whether the error is due to there being no path to
// the given region.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check deployment status is active before unblocking.
2. Treat the error as a no-op for already-finished deployments.
3. If the deployment failed, create a new deployment via 'nomad job run' instead.

Example fix

// before
client.Deployments().Unblock(deployID, nil)
// after
d, _ := client.Deployments().Info(deployID, nil)
if d.Status == "running" { client.Deployments().Unblock(deployID, nil) }

d, err := client.Deployments().Info(deployID, nil)
if err != nil { return err }
if d.Status != "running" { return nil } // cannot unblock

func deploymentActive(d *api.Deployment) bool {
    return d.Status == "running" || d.Status == "pending"
}

err := client.Deployments().Unblock(deployID, nil)
if err != nil && strings.Contains(err.Error(), "terminal deployment") {
    return nil // deployment resolved without unblocking
}

When it happens

Trigger: Calling Deployment.Unblock (or 'nomad deployment unblock') on a deployment that already reached a terminal state.

Common situations: Resuming deployments blocked on quota or evaluation after the deployment auto-failed or completed; scripts unblocking every deployment for a job.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• can't cancel terminal deployment
• can't fail terminal deployment
• can't pause terminal deployment
• can't resume terminal deployment
• can't run terminal deployment

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/7220cc421f4750b5. Report an issue: GitHub.