hashicorp/nomad · error

ErrDriverNotFound

ErrDriverNotFound

Error message

driver not found

What it means

ErrDriverNotFound is the sentinel error returned by the driver manager's Dispense when the requested driver plugin name is not present in the plugin catalog. Callers compare with errors.Is(err, ErrDriverNotFound) to detect that no driver of that name is registered on this client.

Source

Thrown at client/pluginmanager/drivermanager/manager.go:24

import (
	"context"
	"fmt"
	"sync"

	log "github.com/hashicorp/go-hclog"
	plugin "github.com/hashicorp/go-plugin"
	"github.com/hashicorp/nomad/client/pluginmanager"
	"github.com/hashicorp/nomad/client/pluginmanager/drivermanager/state"
	"github.com/hashicorp/nomad/helper/pluginutils/loader"
	"github.com/hashicorp/nomad/nomad/structs"
	"github.com/hashicorp/nomad/plugins/base"
	"github.com/hashicorp/nomad/plugins/drivers"
	pstructs "github.com/hashicorp/nomad/plugins/shared/structs"
)

// ErrDriverNotFound is returned during Dispense when the requested driver
// plugin is not found in the plugin catalog
var ErrDriverNotFound = fmt.Errorf("driver not found")

// Manager is the interface used to manage driver plugins
type Manager interface {
	pluginmanager.PluginManager

	// Dispense returns a drivers.DriverPlugin for the given driver plugin name
	// handling reattaching to an existing driver if available
	Dispense(driver string) (drivers.DriverPlugin, error)
}

// TaskExecHandler is function to be called for executing commands in a task
type TaskExecHandler func(
	ctx context.Context,
	command []string,
	tty bool,
	stream drivers.ExecTaskStream) error

// EventHandler is a callback to be called for a task.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the driver plugin binary is installed on the client and referenced in the client config plugin block
2. Verify with `nomad node status -verbose <node>` that the driver appears in the node's driver list
3. Fix any earlier plugin launch failures so the driver registers into the catalog at client startup
4. In code, check errors.Is(err, drivermanager.ErrDriverNotFound) and fall back to another node/driver

Example fix

// before (client.hcl) — task uses "containerd-driver" but nothing registered
// after
plugin "containerd-driver" {
  config {
    container_runtime = "containerd"
  }
}

// before submitting a job, check the node supports the driver
node, _, _ := client.Nodes().Info(nodeID)
if drv := node.Drivers[driverName]; drv == nil || !drv.Detected {
    return fmt.Errorf("node %s lacks driver %s", nodeID, driverName)
}

func isDriverNotFound(err error) bool {
    return errors.Is(err, drivermanager.ErrDriverNotFound)
}

drv, err := mgr.Dispense(driverName)
if err != nil {
    if errors.Is(err, drivermanager.ErrDriverNotFound) {
        return fmt.Errorf("install/configure driver %q on this client: %w", driverName, err)
    }
    return err
}

When it happens

Trigger: manager.Dispense(driverName) is called with a driver name that has no entry in the manager's plugin catalog — the driver is not built into the client binary, not configured in the client 'plugin' blocks, or failed to register at startup.

Common situations: Task references a driver the Nomad client does not support (external plugin not installed); client config missing the plugin stanza for an external driver; driver failed to launch so it never registered; node fingerprint excludes the driver.

Related errors

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

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