hashicorp/nomad · error

unable to find the nomad binary: %v

Error message

unable to find the nomad binary: %v

What it means

CreateExecutor must locate the current Nomad binary via os.Executable() so it can relaunch it as the executor plugin subprocess. This error means os.Executable() failed, so the executor plugin cannot be started from the running binary path.

Source

Thrown at drivers/shared/executor/utils.go:45

	// searching for an available port
	ExecutorDefaultMinPort = 14000
)

// CreateExecutor launches an executor plugin and returns an instance of the
// Executor interface
func CreateExecutor(
	logger hclog.Logger,
	driverConfig *base.ClientDriverConfig,
	executorConfig *ExecutorConfig,
) (Executor, *plugin.Client, error) {

	c, err := json.Marshal(executorConfig)
	if err != nil {
		return nil, nil, fmt.Errorf("unable to create executor config: %v", err)
	}
	bin, err := os.Executable()
	if err != nil {
		return nil, nil, fmt.Errorf("unable to find the nomad binary: %v", err)
	}

	p := &ExecutorPlugin{
		logger:      logger,
		fsIsolation: executorConfig.FSIsolation,
		compute:     driverConfig.Topology.Compute(),
	}

	config := &plugin.ClientConfig{
		HandshakeConfig:  base.Handshake,
		Plugins:          map[string]plugin.Plugin{"executor": p},
		Cmd:              exec.Command(bin, "executor", string(c)),
		AllowedProtocols: []plugin.Protocol{plugin.ProtocolGRPC},
		Logger:           logger.Named("executor"),
	}

	if driverConfig != nil {
		config.MaxPort = driverConfig.ClientMaxPort

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the Nomad binary exists at its original path while the agent is running (don't delete/replace before restart)
2. Restart the Nomad agent after upgrading/replacing the binary
3. Run Nomad from a standard filesystem path inside a normal container/host environment (verify /proc is mounted on Linux)
4. Check the wrapped OS error (%v) for the underlying reason and address it specifically

Example fix

// before
# rm /usr/local/bin/nomad && start nomad-from-memory
// after
# install new binary, restart service:
# systemctl restart nomad

if _, err := os.Executable(); err != nil { /* resolve/fail early before CreateExecutor */ }

exec, _, err := executor.CreateExecutor(logger, drvCfg, cfg)
if err != nil && strings.Contains(err.Error(), "unable to find the nomad binary") {
    return fmt.Errorf("cannot relaunch executor: %w", err)
}

When it happens

Trigger: os.Executable() returning an error — running in an environment where the executable path cannot be determined (deleted/renamed binary while running, unusual sandbox or init setups, platforms where /proc lookup fails).

Common situations: Nomad binary deleted or replaced on disk while the agent runs; running Nomad under unusual process launchers; minimal containers lacking /proc/self/exe resolution; in-memory or embedded execution contexts.

Related errors

• unable to read rooted allocation directory
• plugin not found
• plugin not executable
• ErrPluginNotExists
• alloc dir must be absolute

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