{"record":{"id":"cdb6bfb5302563c4","repo":"hashicorp/nomad","slug":"unknown-deployment-q","errorCode":null,"errorMessage":"unknown deployment %q","messagePattern":"unknown deployment %q","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/deploymentwatcher/deployments_watcher.go","lineNumber":344,"sourceCode":"\t}\n}\n\n// forceAdd is used to force a lookup of the given deployment object and create\n// a watcher. If the deployment does not exist or is terminal an error is\n// returned.\nfunc (w *Watcher) forceAdd(dID string) (*deploymentWatcher, error) {\n\tsnap, err := w.state.Snapshot()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tdeployment, err := snap.DeploymentByID(nil, dID)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif deployment == nil {\n\t\treturn nil, fmt.Errorf(\"unknown deployment %q\", dID)\n\t}\n\n\treturn w.addLocked(deployment)\n}\n\n// getOrCreateWatcher returns the deployment watcher for the given deployment ID.\nfunc (w *Watcher) getOrCreateWatcher(dID string) (*deploymentWatcher, error) {\n\tw.l.Lock()\n\tdefer w.l.Unlock()\n\n\t// Not enabled so no-op\n\tif !w.enabled {\n\t\treturn nil, notEnabled\n\t}\n\n\twatcher, ok := w.watchers[dID]\n\tif ok {\n\t\treturn watcher, nil","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/deploymentwatcher/deployments_watcher.go#L326-L362","documentation":"forceAdd looks up the deployment by ID in the state store before registering a watcher; if DeploymentByID returns nil the deployment does not exist, so the watcher returns this error rather than watching a nonexistent record.","triggerScenarios":"getOrCreateWatcher -> forceAdd with a deployment ID that is absent from the state store (never existed, typo'd, or already GC'd).","commonSituations":"Calling nomad deployment unblock/promote/fail with a mistyped or GC'd deployment ID; leader-failover rehydration referencing old IDs; automation using stale deployment IDs from an old run.","solutions":["List deployments with `nomad job deployments <job>` or `nomad deployment list` and use a valid active deployment ID","If the deployment was GC'd, create a new deployment by resubmitting the job","Double-check the deployment ID for typos/whitespace in scripts","Persist deployment IDs only for their retention window; re-fetch before acting on old IDs"],"exampleFix":"// before\nnomad deployment unblock 0a1b2c3d  // stale ID\n// after\nnomad deployment list | grep <job>  # copy the current active deployment ID\nnomad deployment unblock <current-id>\n","handlingStrategy":"validation","validationCode":"// resolve a live deployment ID before acting\ndeps, _ := client.Jobs().Deployments(jobID, nil)\nif len(deps) == 0 { /* no deployment to act on */ }","typeGuard":null,"tryCatchPattern":"try {\n    watcher.forceAdd(depID)\n} catch (e) {\n    if (e.message.includes('unknown deployment')) {\n        const deps = await listDeployments(jobID)\n        if (deps.length) await watcher.forceAdd(deps[0].ID)\n    } else { throw e }\n}","preventionTips":["Always fetch deployment IDs from `nomad deployment list` right before use","Don't cache deployment IDs beyond their GC window","Validate ID format/whitespace in scripts before calling deployment APIs"],"tags":["nomad","deployment","not-found","state-store"],"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"}