hashicorp/nomad · error

can't pause terminal deployment

Error message

can't pause terminal deployment

What it means

ErrDeploymentTerminalNoPause: returned by the deployment RPC when a pause is requested on a deployment whose status is no longer active (e.g. cancelled or failed) — terminal deployments cannot be paused.

Source

Thrown at nomad/structs/errors.go:80

	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	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)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Confirm the deployment is still running before pausing ('nomad deployment status <id>').
2. Skip pausing for terminal deployments in automation.
3. Re-fetch the deployment ID from the job's current status rather than a cached value.

Example fix

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

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

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

err := client.Deployments().Pause(deployID, true, "", nil)
if err != nil && strings.Contains(err.Error(), "terminal deployment") {
    return nil // deployment already finished
}

When it happens

Trigger: Calling Deployment.Pause with Pause=true against a completed, failed, or cancelled deployment (e.g. 'nomad deployment pause <terminal-id>').

Common situations: Scripts pausing deployments during maintenance windows that race with the deployment finishing; stale deployment IDs from monitoring.

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 resume terminal deployment
• can't unblock terminal deployment
• can't run terminal deployment

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