hashicorp/nomad · error

consul address must be set on nomad client

Error message

consul address must be set on nomad client

What it means

The Consul HTTP socket hook builds a proxy from the allocation's netns to the Consul HTTP address. The destination address comes from the Nomad client's resolved Consul config (p.config.Addr). If that address is empty — i.e., the client has no Consul address configured — run() aborts with this error since there is no destination to proxy to.

Source

Thrown at client/allocrunner/consul_http_sock_hook.go:213

	if p.runOnce {
		return nil
	}

	// Never restart.
	select {
	case <-p.doneCh:
		p.logger.Trace("consul http socket proxy already shutdown; exiting")
		return nil
	case <-p.ctx.Done():
		p.logger.Trace("consul http socket proxy already done; exiting")
		return nil
	default:
	}

	// consul http dest addr
	destAddr := p.config.Addr
	if destAddr == "" {
		return errors.New("consul address must be set on nomad client")
	}

	socketFile := allocdir.AllocHTTPSocket
	if p.config.Name != structs.ConsulDefaultCluster && p.config.Name != "" {
		socketFile = filepath.Join(allocdir.SharedAllocName, allocdir.TmpDirName,
			"consul_"+p.config.Name+"_http.sock")
	}
	hostHTTPSockPath := filepath.Join(p.allocDir.AllocDirPath(), socketFile)
	if err := maybeRemoveOldSocket(hostHTTPSockPath); err != nil {
		return err
	}

	listener, err := net.Listen("unix", hostHTTPSockPath)
	if err != nil {
		return fmt.Errorf("unable to create unix socket for Consul HTTP endpoint: %w", err)
	}

	// The Consul HTTP socket should be usable by all users in case a task is

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set address in the client's consul config block (e.g. consul { address = "127.0.0.1:8500" }) and restart the Nomad client
2. Ensure the client's Consul auto-discovery resolves (fix Consul agent discovery/fingerprints)
3. Remove the Connect service block from the job if Consul is not actually used on that client
4. Schedule Connect workloads only onto clients with a valid Consul address (use node metadata/constraints)

Example fix

// before (client config)
consul {}
// after
consul {
  address = "127.0.0.1:8500"
}

// verify the client has a Consul address before scheduling Connect work
cfg, err := client.Agent().Self()
if err != nil { return err }
addr, _ := cfg.Config["DebugConfig"].(map[string]interface{})["ConsulAddress"].(string)
if addr == "" { return errors.New("client has no consul address; Connect workloads will fail") }

if err := p.run(); err != nil {
  if err.Error() == "consul address must be set on nomad client" {
    return fmt.Errorf("cannot proxy consul for alloc: configure consul.address on the nomad client: %w", err)
  }
  return err
}

When it happens

Trigger: Starting a Connect-enabled allocation on a Nomad client whose consul.address (or auto-discovered address) is empty — e.g. consul block omitted/empty in client config while the task still requires the Consul HTTP socket proxy.

Common situations: Clients with an empty/omitted consul stanza but a group Connect service block; broken Consul auto-discovery on the client; environments where Consul runs elsewhere and the address was never propagated into the hook config.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• timed out waiting for socket proxy to exit
• Service with provider nomad cannot include Connect blocks
• Connect configuration empty for service %s
• Connect proxy task must not have a service block
• error creating bootstrap configuration for Connect proxy sid

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