hashicorp/nomad · error

init of plugin %s failed: %w

Error message

init of plugin %s failed: %w

What it means

If the dispensed driver implements drivers.DriverIniter, dispense calls initer.Init(i.ctx) to initialize the driver. On failure the plugin instance is killed and this error wraps the init error, associating it with the plugin id.

Source

Thrown at client/pluginmanager/drivermanager/instance.go:234

		// If we still have an error there is a real problem
		if err != nil {
			return nil, fmt.Errorf("failed to start plugin: %v", err)
		}
	}

	// Convert to a driver plugin
	driver, ok := pluginInstance.Plugin().(drivers.DriverPlugin)
	if !ok {
		pluginInstance.Kill()
		return nil, fmt.Errorf("plugin loaded does not implement the driver interface")
	}

	// Initialize the plugin if it supports it.
	if initer, ok := driver.(drivers.DriverIniter); ok {
		if err := initer.Init(i.ctx); err != nil {
			pluginInstance.Kill()
			return nil, fmt.Errorf("init of plugin %s failed: %w", i.id, err)
		}
	}

	// Store the plugin and driver
	i.plugin = pluginInstance
	i.driver = driver

	// Store the reattach config
	if c, ok := pluginInstance.ReattachConfig(); ok {
		if err := i.storeReattach(c); err != nil {
			i.logger.Error("error storing driver plugin reattach config", "error", err)
		}
	}

	return driver, nil
}

// cleanup shutsdown the plugin

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped init error and the plugin's logs for the failing subsystem
2. Fix the driver's environment (docker socket permissions/group membership, containerd socket, required binaries) on the node
3. Correct the plugin's client config block if init validates configuration
4. After fixing, let Nomad redispense the plugin (restart client or wait for the singleton relaunch)

Example fix

// before (host)
$ ls -l /var/run/docker.sock  # 0660 root:root, nomad user not in docker group
// after (host)
usermod -aG docker nomad && systemctl restart nomad

// e.g. docker driver precheck on the node
if _, err := os.Stat("/var/run/docker.sock"); err != nil {
    return fmt.Errorf("docker socket unavailable: %w", err)
}
if err := unix.Access("/var/run/docker.sock", unix.R_OK|unix.W_OK); err != nil {
    return fmt.Errorf("docker socket not accessible to nomad user: %v", err)
}

drv, err := instance.Dispense()
if err != nil {
    var initErr error
    if strings.HasPrefix(err.Error(), "init of plugin ") {
        initErr = err // inspect wrapped init cause; fix node env before retry
    }
    return initErr
}

When it happens

Trigger: initer.Init(i.ctx) returns a non-nil error in instance.dispense — driver-specific initialization (e.g. Docker client setup, libgpu detection, containerd connection) fails within the plugin process.

Common situations: Docker driver can't reach /var/run/docker.sock (permissions/socket missing); containerd driver socket unavailable; QEMU/libvirt environment missing; driver config in client config invalid causing init validation failure.

Related errors

• plugin is shut down
• could not validate task driver capabilities: %v
• failed to start plugin: %v
• plugin loaded does not implement the driver interface
• ErrDriverNotFound

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