hashicorp/nomad · error

failed to read driver manager plugin state: %v

Error message

failed to read driver manager plugin state: %v

What it means

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.

Source

Thrown at client/state/db_bolt.go:916

}

// GetDriverPluginState stores the driver manager's plugin state or returns an
// error.
func (s *BoltStateDB) GetDriverPluginState() (*driverstate.PluginState, error) {
	var ps *driverstate.PluginState

	err := s.db.View(func(tx *boltdd.Tx) error {
		driverBkt := tx.Bucket(driverManagerBucket)
		if driverBkt == nil {
			// No state, return
			return nil
		}

		// Restore Plugin State if it exists
		ps = &driverstate.PluginState{}
		if err := driverBkt.Get(managerPluginStateKey, ps); err != nil {
			if !boltdd.IsErrNotFound(err) {
				return fmt.Errorf("failed to read driver manager plugin state: %v", err)
			}

			// Key not found, reset ps to nil
			ps = nil
		}

		return nil
	})

	if err != nil {
		return nil, err
	}

	return ps, nil
}

// PutDynamicPluginRegistryState stores the dynamic plugin registry's
// state or returns an error.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped error to distinguish decode corruption from bolt I/O failure.
2. Stop the agent and restore state.db from backup if corrupt.
3. Otherwise move state.db aside and restart; driver state is rebuilt as plugins re-register.
4. Verify disk integrity and permissions on the client state_dir.

Example fix

// before
journalctl: failed to read driver manager plugin state: msgpack decode error
// after
systemctl stop nomad
cp /var/lib/nomad/state.db /var/lib/nomad/state.db.backup.bad
rm /var/lib/nomad/state.db && systemctl start nomad

// verify db opens and bucket readable before restore
db.View(func(tx *boltdd.Tx) error {
    b := tx.Bucket([]byte(driverBktName)); if b == nil { return errors.New("missing driver bucket") }
    return nil
})

func isNotFound(err error) bool { return errors.Is(err, boltdd.ErrNotFound) }

if err != nil {
    if !errors.Is(err, boltdd.ErrNotFound) {
        logger.Error("driver plugin state unreadable; rebuilding", "error", err)
        archiveAndResetStateDB(stateDir)
    }
}

When it happens

Trigger: driverBkt.Get(managerPluginStateKey) fails with a decode or bolt I/O error while restoring driver plugin state into driverstate.PluginState.

Common situations: Corrupt state.db after unclean shutdown, msgpack incompatibility from a Nomad downgrade/upgrade, or failing storage backing the client data directory.

Related errors

• failed to read device manager plugin state: %v
• failed to read dynamic plugin registry state: %v
• error parsing: root should be an object
• cannot specify Accessor ID
• network already configured but not found in state

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/f81b0baa4732dcdd. Report an issue: GitHub.