{"record":{"id":"dfd7200e08fe44a6","repo":"hashicorp/nomad","slug":"dev-connect-requires-a-consul-binary-in-nomad-s","errorCode":null,"errorMessage":"-dev-connect requires a 'consul' binary in Nomad's $PATH","messagePattern":"-dev-connect requires a 'consul' binary in Nomad's \\$PATH","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/config.go","lineNumber":1731,"sourceCode":"\t\t\t// strictly speaking -dev-connect only binds to the\n\t\t\t// non-localhost interface, but given its purpose\n\t\t\t// is to support a feature with network namespaces\n\t\t\t// we'll return an error here rather than let the agent\n\t\t\t// come up and fail unexpectedly to run jobs\n\t\t\treturn fmt.Errorf(\"-dev-connect is only supported on linux.\")\n\t\t}\n\t\tu, err := users.Current()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\n\t\t\t\t\"-dev-connect uses network namespaces and is only supported for root: %v\", err)\n\t\t}\n\t\tif u.Uid != \"0\" {\n\t\t\treturn fmt.Errorf(\n\t\t\t\t\"-dev-connect uses network namespaces and is only supported for root.\")\n\t\t}\n\t\t// Ensure Consul is on PATH\n\t\tif _, err := exec.LookPath(\"consul\"); err != nil {\n\t\t\treturn fmt.Errorf(\"-dev-connect requires a 'consul' binary in Nomad's $PATH\")\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (mode *devModeConfig) networkConfig() error {\n\tif runtime.GOOS == \"windows\" {\n\t\tmode.bindAddr = \"127.0.0.1\"\n\t\tmode.iface = \"Loopback Pseudo-Interface 1\"\n\t\treturn nil\n\t}\n\tif runtime.GOOS == \"darwin\" {\n\t\tmode.bindAddr = \"127.0.0.1\"\n\t\tmode.iface = \"lo0\"\n\t\treturn nil\n\t}\n\tif mode != nil && mode.connectMode {\n\t\t// if we hit either of the errors here we're in a weird situation","sourceCodeStart":1713,"sourceCodeEnd":1749,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/config.go#L1713-L1749","documentation":"-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.","triggerScenarios":"Running -dev-connect on Linux as root but without a `consul` executable in $PATH (or the PATH of the process running Nomad).","commonSituations":"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).","solutions":["Install Consul and ensure the binary is in the PATH of the Nomad process.","If consul is elsewhere, extend PATH for the Nomad service (Environment=PATH=... in systemd) or symlink the binary into a PATH dir.","Verify with `which consul` in the same context Nomad runs."],"exampleFix":"# before\n$ which consul   # not found\n# after\nsudo ln -s /opt/consul/bin/consul /usr/local/bin/consul\nsudo nomad agent -dev-connect","handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"consul\"); err != nil {\n  return errors.New(\"install consul or add it to PATH before -dev-connect\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check `which consul` in the same shell/service context that runs Nomad","Remember systemd has a minimal default PATH","Pin and install consul alongside nomad in dev setups"],"tags":["path","consul","dev-connect","environment"],"backgroundTag":"binary-not-found-on-path","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}