hashicorp/nomad · error

-dev-connect requires a 'consul' binary in Nomad's $PATH

Error message

-dev-connect requires a 'consul' binary in Nomad's $PATH

What it means

-dev-connect builds a Consul Connect environment and needs the `consul` binary accessible to spawn Consul. Validation performs exec.LookPath("consul") and fails with this error if it is not found in Nomad's PATH.

Source

Thrown at command/agent/config.go:1731

			// strictly speaking -dev-connect only binds to the
			// non-localhost interface, but given its purpose
			// is to support a feature with network namespaces
			// we'll return an error here rather than let the agent
			// come up and fail unexpectedly to run jobs
			return fmt.Errorf("-dev-connect is only supported on linux.")
		}
		u, err := users.Current()
		if err != nil {
			return fmt.Errorf(
				"-dev-connect uses network namespaces and is only supported for root: %v", err)
		}
		if u.Uid != "0" {
			return fmt.Errorf(
				"-dev-connect uses network namespaces and is only supported for root.")
		}
		// Ensure Consul is on PATH
		if _, err := exec.LookPath("consul"); err != nil {
			return fmt.Errorf("-dev-connect requires a 'consul' binary in Nomad's $PATH")
		}
	}
	return nil
}

func (mode *devModeConfig) networkConfig() error {
	if runtime.GOOS == "windows" {
		mode.bindAddr = "127.0.0.1"
		mode.iface = "Loopback Pseudo-Interface 1"
		return nil
	}
	if runtime.GOOS == "darwin" {
		mode.bindAddr = "127.0.0.1"
		mode.iface = "lo0"
		return nil
	}
	if mode != nil && mode.connectMode {
		// if we hit either of the errors here we're in a weird situation

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Install Consul and ensure the binary is in the PATH of the Nomad process.
2. If consul is elsewhere, extend PATH for the Nomad service (Environment=PATH=... in systemd) or symlink the binary into a PATH dir.
3. Verify with `which consul` in the same context Nomad runs.

Example fix

# before
$ which consul   # not found
# after
sudo ln -s /opt/consul/bin/consul /usr/local/bin/consul
sudo nomad agent -dev-connect

if _, err := exec.LookPath("consul"); err != nil {
  return errors.New("install consul or add it to PATH before -dev-connect")
}

When it happens

Trigger: Running -dev-connect on Linux as root but without a `consul` executable in $PATH (or the PATH of the process running Nomad).

Common situations: Nomad installed via package without Consul installed; Consul installed to a non-PATH directory; systemd units with a restricted PATH (e.g. /usr/bin only while consul is in /usr/local/bin).

Related errors

• configuration path must be a directory: %s
• no one-time token returned
• no ACL token returned
• errMissingACLRoleID
• errMissingACLAuthMethodName

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