hashicorp/nomad · error

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

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.

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)

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

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

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

• -dev-connect uses network namespaces and is only supported f
• Unable to find nobody user: %w
• Couldn't change owner/group of %v to (uid: %v, gid: %v): %w
• Failed to delete proc directory %q: %w
• error changing owner/group: %w

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