{"record":{"id":"1c6be2edd14dfb5e","repo":"hashicorp/nomad","slug":"deployment-not-found","errorCode":null,"errorMessage":"deployment not found","messagePattern":"deployment not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/deployment_endpoint.go","lineNumber":128,"sourceCode":"\n\t// Validate the arguments\n\tif args.DeploymentID == \"\" {\n\t\treturn fmt.Errorf(\"missing deployment ID\")\n\t}\n\n\t// Lookup the deployment\n\tsnap, err := d.srv.fsm.State().Snapshot()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tws := memdb.NewWatchSet()\n\tdeploy, err := snap.DeploymentByID(ws, args.DeploymentID)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif deploy == nil {\n\t\treturn fmt.Errorf(\"deployment not found\")\n\t}\n\n\t// Check namespace submit-job permissions\n\tif aclObj, err := d.srv.ResolveACL(args); err != nil {\n\t\treturn err\n\t} else if !aclObj.AllowNsOpAnyOf(deploy.Namespace,\n\t\tacl.NamespaceCapabilitySubmitJob,\n\t\tacl.NamespaceCapabilityFailDeployment,\n\t) {\n\t\treturn structs.ErrPermissionDenied\n\t}\n\n\tif !deploy.Active() {\n\t\treturn structs.ErrDeploymentTerminalNoFail\n\t}\n\n\t// Call into the deployment watcher\n\treturn d.srv.deploymentWatcher.FailDeployment(args, reply)","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/deployment_endpoint.go#L110-L146","documentation":"After validating the ID, Deployment.Fail looks the deployment up in the state store via DeploymentByID. If the store returns nil — the ID is well-formed but no deployment with that UUID exists — this error is thrown. Unlike 'missing deployment ID', the caller supplied an identifier; it simply does not match any deployment in Nomad's state (or was deleted/GC'd).","triggerScenarios":"Calling nomad deployment fail <id> / POST /v1/deployment/fail with a UUID that was never created, belongs to another cluster, or whose record was removed; typos or truncated UUIDs.","commonSituations":"Cross-environment scripts reusing a deployment ID from staging in production; failing a deployment after the associated job was purged; stale deployment IDs cached in CI configuration after a Nomad server state restore.","solutions":["Verify the ID with nomad deployment status <id> or GET /v1/deployment/<id> first","Re-fetch the current deployment ID from the job: nomad job status <job> or GET /v1/job/<job>/deployments","Confirm you are targeting the correct Nomad cluster/region (deployment IDs are per-cluster)","If the deployment is already terminal, it cannot be failed again — check its Status first"],"exampleFix":"// before\nnomad deployment fail f47ac10b-58cc-...   // id from another cluster\n\n// after\nDID=$(nomad job status web | awk '/Deployment/{print $2; exit}')\nnomad deployment status \"$DID\" && nomad deployment fail \"$DID\"","handlingStrategy":"validation","validationCode":"dep, _, err := client.Deployments().Get(id)\nif err != nil || dep == nil {\n    return fmt.Errorf(\"deployment %s does not exist in this cluster\", id)\n}","typeGuard":"func deploymentExists(c *api.Client, id string) bool {\n    d, _, err := c.Deployments().Get(id)\n    return err == nil && d != nil\n}","tryCatchPattern":"_, _, err := client.Deployments().Fail(id, nil)\nif err != nil && strings.Contains(err.Error(), \"deployment not found\") {\n    return fmt.Errorf(\"stale deployment ID %s; re-resolve from job\", id)\n}","preventionTips":["Confirm IDs against the target cluster (NOMAD_ADDR/NOMAD_REGION) before writes","Re-fetch the deployment ID from the job rather than caching across runs","Expect ID invalidation after Nomad server restores or job purges","Check deployment Status is running before failing"],"tags":["deployment","nomad","not-found","lookup"],"backgroundTag":"resource-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"}