{"record":{"id":"b5cc2537ce75512b","repo":"hashicorp/nomad","slug":"alloc-entry-not-found","errorCode":null,"errorMessage":"alloc entry not found","messagePattern":"alloc entry not found","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/state/upgrade.go","lineNumber":193,"sourceCode":"\t\t\t\t\t\"key\", string(k), \"value_bytes\", len(v),\n\t\t\t\t)\n\n\t\t\t\tif err := cur.Delete(); err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\t// Nested buckets are tasks\n\t\t\ttaskBuckets = append(taskBuckets, k)\n\t\t}\n\t}\n\n\t// If the alloc entry was not found, abandon this allocation as the\n\t// state has been corrupted.\n\tif !allocFound {\n\t\treturn fmt.Errorf(\"alloc entry not found\")\n\t}\n\n\t// Upgrade tasks\n\tfor _, taskBucket := range taskBuckets {\n\t\ttaskName := string(taskBucket)\n\t\ttaskLogger := logger.With(\"task_name\", taskName)\n\n\t\ttaskBkt := bkt.Bucket(taskBucket)\n\t\tif taskBkt == nil {\n\t\t\t// This should never happen as we just read the bucket.\n\t\t\treturn fmt.Errorf(\"unexpected bucket missing %q\", taskName)\n\t\t}\n\n\t\toldState, err := upgradeTaskBucket(taskLogger, taskBkt)\n\t\tif err != nil {\n\t\t\ttaskLogger.Warn(\"dropping invalid task due to error while upgrading state\",\n\t\t\t\t\"error\", err,\n\t\t\t)","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/state/upgrade.go#L175-L211","documentation":"While upgrading one alloc's bucket, the code scans task buckets for an entry representing the alloc itself (alloc entry). If none was found, the allocation's state is considered corrupted, the alloc is abandoned with this error, and (per the caller) the alloc's state is dropped rather than upgraded.","triggerScenarios":"upgradeAllocBucket iterates all buckets/keys under the alloc bucket and never finds the alloc entry — e.g. the alloc bucket contains only task buckets or partial writes from a crash left the alloc record missing.","commonSituations":"Client crash mid-write to state.db leaving a partially written alloc bucket; restore from an inconsistent backup; manual tampering with state.db.","solutions":["This is expected to be tolerated: the caller logs 'dropping invalid allocation' and deletes the bucket — confirm via agent logs which alloc was dropped.","Reconcile state: the client re-syncs allocs from the Nomad servers, so the dropped alloc re-registers.","If many allocs are dropped, restore state.db from backup or wipe state and let the client rebuild.","Avoid killing the agent mid-write (use graceful shutdown)."],"exampleFix":"// before\nalloc a1b2 state corrupt -> alloc entry not found, alloc dropped\n// after\n# verify server-side alloc is running\nnomad status <alloc-id>  # client re-syncs; no action usually needed","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := upgradeAllocBucket(logger, tx, bkt, allocID); err != nil {\n    if err.Error() == \"alloc entry not found\" {\n        allocLogger.Warn(\"dropping corrupted alloc; client will re-sync from servers\", \"error\", err)\n        if derr := allocationsBucket.DeleteBucket([]byte(allocID)); derr != nil {\n            return derr\n        }\n        continue\n    }\n    return err\n}","preventionTips":["Use graceful shutdown (SIGINT) for nomad clients","Rely on server reconciliation to restore dropped allocs","Back up state.db before upgrades","Alert on 'dropping invalid allocation' log lines"],"tags":["bolt","upgrade","corruption","allocation"],"backgroundTag":"corrupt-allocation-state","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"}