{"record":{"id":"951d7767b9de40c0","repo":"hashicorp/nomad","slug":"deployment-watcher-not-enabled","errorCode":null,"errorMessage":"deployment watcher not enabled","messagePattern":"deployment watcher not enabled","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"nomad/deploymentwatcher/deployments_watcher.go","lineNumber":35,"sourceCode":"\t\"github.com/hashicorp/nomad/nomad/state\"\n\t\"github.com/hashicorp/nomad/nomad/structs\"\n)\n\nconst (\n\t// LimitStateQueriesPerSecond is the number of state queries allowed per\n\t// second\n\tLimitStateQueriesPerSecond = 100.0\n\n\t// CrossDeploymentUpdateBatchDuration is the duration in which allocation\n\t// desired transition and evaluation creation updates are batched across\n\t// all deployment watchers before committing to Raft.\n\tCrossDeploymentUpdateBatchDuration = 250 * time.Millisecond\n)\n\nvar (\n\t// notEnabled is the error returned when the deployment watcher is not\n\t// enabled\n\tnotEnabled = fmt.Errorf(\"deployment watcher not enabled\")\n)\n\n// DeploymentRaftEndpoints exposes the deployment watcher to a set of functions\n// to apply data transforms via Raft.\ntype DeploymentRaftEndpoints interface {\n\t// UpsertJob is used to upsert a job\n\tUpsertJob(job *structs.Job) (uint64, error)\n\n\t// UpdateDeploymentStatus is used to make a deployment status update\n\t// and potentially create an evaluation.\n\tUpdateDeploymentStatus(u *structs.DeploymentStatusUpdateRequest) (uint64, error)\n\n\t// UpdateDeploymentPromotion is used to promote canaries in a deployment\n\tUpdateDeploymentPromotion(req *structs.ApplyDeploymentPromoteRequest) (uint64, error)\n\n\t// UpdateDeploymentAllocHealth is used to set the health of allocations in a\n\t// deployment\n\tUpdateDeploymentAllocHealth(req *structs.ApplyDeploymentAllocHealthRequest) (uint64, error)","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/deploymentwatcher/deployments_watcher.go#L17-L53","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the target server is a fully functioning Nomad server with deployment watching enabled (default behavior)","Do not treat this as a deploy failure on clients — it is a server configuration/role issue","If running custom/test setups, construct the watcher with enabled=true and a valid allocUpdateBatcher","Retry the request against a different server that hosts the deployment watcher"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before calling deployment endpoints, confirm the server has the watcher enabled\nenabled := watcher != nil && watcher.Enabled() && watcher.allocUpdateBatcher != nil","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Deploy standard Nomad servers (watcher enabled by default)","Don't route deployment RPCs to servers without the deployment watcher","In tests, construct the watcher with enabled=true and a real allocUpdateBatcher"],"tags":["nomad","configuration","deployment-watcher"],"backgroundTag":"feature-not-enabled","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}