{"record":{"id":"d2ca8ee80624cdef","repo":"hashicorp/nomad","slug":"deployment-id-not-found-q","errorCode":null,"errorMessage":"deployment id not found: %q","messagePattern":"deployment id not found: %q","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/deploymentwatcher/deployment_watcher.go","lineNumber":667,"sourceCode":"\treturn res, nil\n}\n\n// shouldFail returns whether the job should be failed and whether it should\n// rolled back to an earlier stable version by examining the allocations in the\n// deployment.\nfunc (w *deploymentWatcher) shouldFail() (fail, rollback bool, err error) {\n\tsnap, err := w.state.Snapshot()\n\tif err != nil {\n\t\treturn false, false, err\n\t}\n\n\td, err := snap.DeploymentByID(nil, w.deploymentID)\n\tif err != nil {\n\t\treturn false, false, err\n\t}\n\tif d == nil {\n\t\t// The deployment wasn't in the state store, possibly due to a system gc\n\t\treturn false, false, fmt.Errorf(\"deployment id not found: %q\", w.deploymentID)\n\t}\n\n\tfail = false\n\tif d.Status == structs.DeploymentStatusPaused {\n\t\treturn false, false, nil\n\t}\n\tfor tg, dstate := range d.TaskGroups {\n\t\t// If we are in a canary state we fail if there aren't enough healthy\n\t\t// allocs to satisfy DesiredCanaries\n\t\tif dstate.DesiredCanaries > 0 && !dstate.Promoted {\n\t\t\tif dstate.HealthyAllocs >= dstate.DesiredCanaries {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t} else if dstate.HealthyAllocs >= dstate.DesiredTotal {\n\t\t\tcontinue\n\t\t}\n\n\t\t// We have failed this TG","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/deploymentwatcher/deployment_watcher.go#L649-L685","documentation":"deploymentwatcher fails the shouldFail check when the deployment being watched cannot be found in the state store. Nomad throws this because a watcher can outlive its deployment record — most commonly after a system garbage collection removes the deployment while the watcher is still active. The watcher cannot evaluate whether the deployment should fail, so it returns an error instead of a decision.","triggerScenarios":"watch() calls shouldFail, which does snap.DeploymentByID(nil, w.deploymentID); if the state store returns nil for the deployment (e.g. it was GC'd out of state between watcher creation and this evaluation), the error is returned.","commonSituations":"A long-running deployment whose job was deregistered and state was garbage collected; compacted/GC'd state on busy clusters; races where the deployment finishes and is GC'd while its watcher is still ticking.","solutions":["Verify the deployment still exists with `nomad deployment status <id>`; if it was GC'd, this error is expected and the watcher will be cleaned up","Re-register or re-run the job to create a fresh deployment and watcher","Check state store GC settings (default eval/deployment GC intervals) if this fires too eagerly","Restart the Nomad server leader if stale watchers persist after GC"],"exampleFix":"// no caller-side fix; confirm deployment exists before relying on its watcher\nnomad deployment status <deployment-id>  # if 'not found', the deployment was GC'd\n","handlingStrategy":"fallback","validationCode":"nomad deployment status <deployment-id>  # must return an ACTIVE deployment, not 'not found'","typeGuard":"// Go-style guard before acting on a deployment\nfunc deploymentUsable(d *structs.Deployment) bool { return d != nil && d.Active() }","tryCatchPattern":"try {\n    watcher.shouldFail(depID)\n} catch (e) {\n    if (e.message.includes('deployment id not found')) {\n        // deployment GC'd: treat as terminal, re-run job for a fresh deployment\n        rerunJob(jobID)\n    } else { throw e }\n}","preventionTips":["Re-fetch the deployment from the API before acting on stored IDs","Expect deployments to be GC'd and treat 'not found' as terminal, not retryable","Keep job registration alive while a deployment should remain watchable"],"tags":["nomad","state-store","garbage-collection","deployment"],"backgroundTag":"deployment-not-found","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"}