hashicorp/nomad · error

-dev-connect is only supported on linux.

Error message

-dev-connect is only supported on linux.

What it means

The -dev-connect dev mode relies on Linux network namespaces, so agent config validation rejects it on any other OS. This is a hard guard: the agent would otherwise start and fail later when running connect jobs.

Source

Thrown at command/agent/config.go:1718

	bindAddr string
	iface    string
}

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
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run the agent on Linux (native or a Linux VM/container).
2. Use regular -dev mode plus a local Consul with Connect enabled instead of -dev-connect.
3. Use Docker Desktop/colima with a Linux VM to get a linux environment.

Example fix

// before (macOS)
nomad agent -dev-connect
// after (Linux or VM)
nomad agent -dev
// or run inside a Linux container/VM for -dev-connect

if runtime.GOOS != "linux" {
  return errors.New("-dev-connect requires Linux; use -dev or run in a Linux VM")
}

When it happens

Trigger: Running `nomad agent -dev-connect` (or DevConnect mode in config) on darwin/windows; runtime.GOOS != "linux" at config validation time.

Common situations: Trying the quickstart dev mode on macOS laptops; CI containers on non-linux hosts; following Linux-only tutorials on other platforms.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• journald log monitoring only available on linux
• ErrCgroupMustBeSet
• Unable to find nobody user: %w
• Couldn't change owner/group of %v to (uid: %v, gid: %v): %w
• Unable to convert Uid to an int: %w

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