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: %v

What it means

After confirming the OS is Linux, -dev-connect checks the current user. If the OS call to get the current user fails, the agent cannot verify privileges needed for network namespaces and returns this error including the underlying reason.

Source

Thrown at command/agent/config.go:1722

func (mode *devModeConfig) enabled() bool {
	return mode.defaultMode || mode.connectMode ||
		mode.consulMode || mode.vaultMode
}

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"

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run the agent as root in a proper Linux environment.
2. Fix the container image so user lookup works (ensure /etc/passwd exists and the current uid is defined).
3. Inspect the wrapped error (%v) to identify the lookup failure.

Example fix

# before (fails: no user entry)
docker run --user 12345 nomad-dev nomad agent -dev-connect
# after
docker run --user root nomad-dev nomad agent -dev-connect

u, err := user.Current()
if err != nil || u.Uid != "0" {
  return errors.New("-dev-connect must run as root on Linux")
}

When it happens

Trigger: users.Current() returns an error during -dev-connect config validation — e.g. running in environments without a resolvable uid (stripped containers, unusual NSS setups).

Common situations: Running the agent in minimal Docker images lacking /etc/passwd entries; sandboxed environments where user lookup fails.

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/628cb0b755cdcf54. Report an issue: GitHub.