hashicorp/nomad · error

-dev-connect uses network namespaces and is only supported…

Error message

-dev-connect uses network namespaces and is only supported for root.

What it means

devModeConfig.validate rejects -dev-connect when the current user could not be identified or is not root: Consul Connect with -dev requires Linux network namespaces, which only root can create, so the dev agent refuses to start rather than failing later.

Solutions

  1. Run the agent with sudo or as root.
  2. Configure the service (systemd unit, container) to run as root.
  3. Use non-connect -dev mode if root is not possible.

Example fix

# before
nomad agent -dev-connect
# after
sudo nomad agent -dev-connect
Defensive patterns

Strategy: validation

Validate before calling

if os.Geteuid() != 0 {
  return errors.New("-dev-connect requires root (network namespaces)")
}

Prevention

When it happens

Trigger: Running `nomad agent -dev-connect` as a non-root Linux user (uid != 0).

Common situations: Developers running the dev agent under their own account; CI runners without privileged mode; systemd units lacking User=root.

Related errors


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

Appendix: source

Thrown at command/agent/config.go:1726

}

func (mode *devModeConfig) validate() error {
	if mode.connectMode {
		if runtime.GOOS != "linux" {
			// 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"

View on GitHub (pinned to 482b49bf1a)