hashicorp/nomad · warning

deployment watcher not enabled

Error message

deployment watcher not enabled

What it means

notEnabled is a package-level sentinel error returned when the deployment watcher is invoked on a server that has deployment watching disabled (usually servers with reduced Raft endpoints/agent role). getOrCreateWatcher and createUpdate short-circuit with this error instead of doing work, since the watcher feature is not active on this server.

Source

Thrown at nomad/deploymentwatcher/deployments_watcher.go:35

	"github.com/hashicorp/nomad/nomad/state"
	"github.com/hashicorp/nomad/nomad/structs"
)

const (
	// LimitStateQueriesPerSecond is the number of state queries allowed per
	// second
	LimitStateQueriesPerSecond = 100.0

	// CrossDeploymentUpdateBatchDuration is the duration in which allocation
	// desired transition and evaluation creation updates are batched across
	// all deployment watchers before committing to Raft.
	CrossDeploymentUpdateBatchDuration = 250 * time.Millisecond
)

var (
	// notEnabled is the error returned when the deployment watcher is not
	// enabled
	notEnabled = fmt.Errorf("deployment watcher not enabled")
)

// DeploymentRaftEndpoints exposes the deployment watcher to a set of functions
// to apply data transforms via Raft.
type DeploymentRaftEndpoints interface {
	// UpsertJob is used to upsert a job
	UpsertJob(job *structs.Job) (uint64, error)

	// UpdateDeploymentStatus is used to make a deployment status update
	// and potentially create an evaluation.
	UpdateDeploymentStatus(u *structs.DeploymentStatusUpdateRequest) (uint64, error)

	// UpdateDeploymentPromotion is used to promote canaries in a deployment
	UpdateDeploymentPromotion(req *structs.ApplyDeploymentPromoteRequest) (uint64, error)

	// UpdateDeploymentAllocHealth is used to set the health of allocations in a
	// deployment
	UpdateDeploymentAllocHealth(req *structs.ApplyDeploymentAllocHealthRequest) (uint64, error)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the target server is a fully functioning Nomad server with deployment watching enabled (default behavior)
2. Do not treat this as a deploy failure on clients — it is a server configuration/role issue
3. If running custom/test setups, construct the watcher with enabled=true and a valid allocUpdateBatcher
4. Retry the request against a different server that hosts the deployment watcher

// before calling deployment endpoints, confirm the server has the watcher enabled
enabled := watcher != nil && watcher.Enabled() && watcher.allocUpdateBatcher != nil

When it happens

Trigger: createUpdate calls the alloc update batcher when w.allocUpdateBatcher is nil, or getOrCreateWatcher checks !w.enabled; both return notEnabled. This happens when deployments_watcher was created with enabled=false or without an allocUpdateBatcher.

Common situations: Calling deployment-related job APIs against a server where the deployment watcher isn't enabled; tests or region configurations that disable deployment watching; routing a deployment RPC to the wrong server class.

Related errors

• no CNI network config found
• dynamic workload users disabled
• no auth method config or client assertion
• Job registration, dispatch, and scale are disabled by the sc
• Reschedule policy has unlimited attempts enabled and a low d

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