hashicorp/nomad · warning

can't unblock running deployment

Error message

can't unblock running deployment

What it means

ErrDeploymentRunningNoUnblock is returned when an unblock request targets a deployment that is still running (not paused/blocked). Unblock only makes sense on a paused or blocked deployment; issuing it against an already-running deployment is rejected to avoid redundant or contradictory state transitions.

Source

Thrown at nomad/structs/errors.go:86

	// 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.
func IsErrNoRegionPath(err error) bool {
	return err != nil && strings.Contains(err.Error(), errNoRegionPath)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the deployment's Status/StatusDescription via 'nomad deployment status <id>' and only unblock if it is paused or blocked
2. Treat the error as a no-op in scripts (the desired state is already achieved)
3. Re-check whether the correct deployment ID was targeted; listing deployments for the job can reveal the paused one
4. Refresh local state after the first unblock so subsequent retries are skipped

Example fix

// before
client.Deployments().Unblock(depID, nil, nil)
// after
dep, _, _ := client.Deployments().Info(depID, nil)
if dep != nil && dep.Status == structs.DeploymentStatusPaused {
    client.Deployments().Unblock(depID, nil, nil)
}

dep, _, err := client.Deployments().Info(depID, nil)
if err == nil && dep != nil && dep.Status == api.DeploymentStatusRunning {
    return nil // nothing to unblock
}

func deploymentNeedsUnblock(dep *api.Deployment) bool {
    return dep != nil && dep.Status == api.DeploymentStatusPaused
}

_, _, err := client.Deployments().Unblock(depID, nil, nil)
if err != nil && strings.Contains(err.Error(), "running deployment") {
    log.Printf("deployment %s already running; unblock not needed", depID)
    return nil
}
return err

When it happens

Trigger: Calling the Deployment.Unblock RPC (nomad deployment unblock) with the ID of a deployment whose state is already 'running' rather than 'paused' or 'blocked'.

Common situations: Operator runs 'nomad deployment unblock' on the wrong deployment ID or on a deployment that already auto-resumed; a script retries unblock after it already succeeded; failover automation unblocks a deployment the scheduler already unblocked.

Related errors

• can't set health of allocations for a terminal deployment
• deployment promotion cannot be undone
• can't cancel terminal deployment
• can't fail terminal deployment
• can't pause terminal deployment

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