{"record":{"id":"f81b0baa4732dcdd","repo":"hashicorp/nomad","slug":"failed-to-read-driver-manager-plugin-state-v","errorCode":null,"errorMessage":"failed to read driver manager plugin state: %v","messagePattern":"failed to read driver manager plugin state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/state/db_bolt.go","lineNumber":916,"sourceCode":"}\n\n// GetDriverPluginState stores the driver manager's plugin state or returns an\n// error.\nfunc (s *BoltStateDB) GetDriverPluginState() (*driverstate.PluginState, error) {\n\tvar ps *driverstate.PluginState\n\n\terr := s.db.View(func(tx *boltdd.Tx) error {\n\t\tdriverBkt := tx.Bucket(driverManagerBucket)\n\t\tif driverBkt == nil {\n\t\t\t// No state, return\n\t\t\treturn nil\n\t\t}\n\n\t\t// Restore Plugin State if it exists\n\t\tps = &driverstate.PluginState{}\n\t\tif err := driverBkt.Get(managerPluginStateKey, ps); err != nil {\n\t\t\tif !boltdd.IsErrNotFound(err) {\n\t\t\t\treturn fmt.Errorf(\"failed to read driver manager plugin state: %v\", err)\n\t\t\t}\n\n\t\t\t// Key not found, reset ps to nil\n\t\t\tps = nil\n\t\t}\n\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn ps, nil\n}\n\n// PutDynamicPluginRegistryState stores the dynamic plugin registry's\n// state or returns an error.","sourceCodeStart":898,"sourceCodeEnd":934,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/state/db_bolt.go#L898-L934","documentation":"Same pattern as the device manager variant: returned during state restore when the driver manager's plugin-state key cannot be read from BoltDB. The underlying error (non-NotFound) is wrapped; a missing key is explicitly tolerated and treated as no plugin state.","triggerScenarios":"driverBkt.Get(managerPluginStateKey) fails with a decode or bolt I/O error while restoring driver plugin state into driverstate.PluginState.","commonSituations":"Corrupt state.db after unclean shutdown, msgpack incompatibility from a Nomad downgrade/upgrade, or failing storage backing the client data directory.","solutions":["Read the wrapped error to distinguish decode corruption from bolt I/O failure.","Stop the agent and restore state.db from backup if corrupt.","Otherwise move state.db aside and restart; driver state is rebuilt as plugins re-register.","Verify disk integrity and permissions on the client state_dir."],"exampleFix":"// before\njournalctl: failed to read driver manager plugin state: msgpack decode error\n// after\nsystemctl stop nomad\ncp /var/lib/nomad/state.db /var/lib/nomad/state.db.backup.bad\nrm /var/lib/nomad/state.db && systemctl start nomad","handlingStrategy":"fallback","validationCode":"// verify db opens and bucket readable before restore\ndb.View(func(tx *boltdd.Tx) error {\n    b := tx.Bucket([]byte(driverBktName)); if b == nil { return errors.New(\"missing driver bucket\") }\n    return nil\n})","typeGuard":"func isNotFound(err error) bool { return errors.Is(err, boltdd.ErrNotFound) }","tryCatchPattern":"if err != nil {\n    if !errors.Is(err, boltdd.ErrNotFound) {\n        logger.Error(\"driver plugin state unreadable; rebuilding\", \"error\", err)\n        archiveAndResetStateDB(stateDir)\n    }\n}","preventionTips":["Avoid abrupt kills (SIGKILL) of the nomad agent","Take state.db.backup before Nomad upgrades","Match Nomad versions when restoring node state","Monitor disk health (SMART) on client nodes"],"tags":["bolt","state-store","deserialization","nomad"],"backgroundTag":"boltdb-deserialization-failed","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"}