hashicorp/nomad · error · errEnvoyBootstrapError

error creating bootstrap configuration for Connect proxy sid

Error message

error creating bootstrap configuration for Connect proxy sidecar

What it means

errEnvoyBootstrapError is the sentinel for failures while building the Envoy bootstrap configuration for a Consul Connect proxy/gateway task. It is wrapped (fmt.Errorf("%w: %v; see: <https://developer.hashicorp.com/nomad/s/envoy-bootstrap-error>")) inside a recoverable error both when the `consul connect envoy -bootstrap` command fails (line 414) and when the Consul API returns an error (line 681). Because it's recoverable, Nomad retries the Prestart hook with backoff/jitter (envoyBootstrapMaxJitter) before failing the task.

Source

Thrown at client/allocrunner/taskrunner/envoy_bootstrap_hook.go:50

const envoyBootstrapHookName = "envoy_bootstrap"

const (
	// envoyBootstrapWaitTime is the amount of time this hook should wait on Consul
	// objects to be created before giving up.
	envoyBootstrapWaitTime = 60 * time.Second

	// envoyBootstrapInitialGap is the initial amount of time the envoy bootstrap
	// retry loop will wait, exponentially increasing each iteration, not including
	// jitter.
	envoyBootstrapInitialGap = 1 * time.Second

	// envoyBootstrapMaxJitter is the maximum amount of jitter applied to the
	// wait gap each iteration of the envoy bootstrap retry loop.
	envoyBootstrapMaxJitter = 500 * time.Millisecond
)

var (
	errEnvoyBootstrapError = errors.New("error creating bootstrap configuration for Connect proxy sidecar")
)

type consulTransportConfig struct {
	HTTPAddr   string // required
	Auth       string // optional, env CONSUL_HTTP_AUTH
	SSL        string // optional, env CONSUL_HTTP_SSL
	VerifySSL  string // optional, env CONSUL_HTTP_SSL_VERIFY
	GRPCCAFile string // optional, arg -grpc-ca-file
	CAFile     string // optional, arg -ca-file
	CertFile   string // optional, arg -client-cert
	KeyFile    string // optional, arg -client-key
	Namespace  string // optional, only consul Enterprise, env CONSUL_NAMESPACE
	// CAPath (dir) not supported by Nomad's config object
}

func newConsulTransportConfig(cc *config.ConsulConfig) consulTransportConfig {
	return consulTransportConfig{
		HTTPAddr:   cc.Addr,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped sub-error in the task log (it includes the underlying command/API message and the fix guide URL); address that root cause directly.
2. Verify Consul connectivity from the client: CONSUL_HTTP_ADDR, TLS (ca/cert/key) and ACL token settings in the nomad agent consul block; test with `consul members` and `consul connect envoy -bootstrap` manually.
3. Check ACL permissions: the token needs service:write for the connect service and node:read; update the policy.
4. Confirm envoy version compatibility (consul version ↔ envoy version matrix) and reinstall the matching envoy binary.
5. If transient (Consul restart), let the recoverable retry succeed; otherwise nomad alloc stop and reschedule after fixing Consul.

Example fix

// before: nomad agent lacking consul ACL config
consul {
  address = "127.0.0.1:8500"
}
// after:
consul {
  address = "127.0.0.1:8500"
  token   = "<token-with-service:write-and-node:read>"
  grpc_address = "127.0.0.1:8502"
  tls {
    ca_file   = "/etc/consul/tls/ca.pem"
    cert_file = "/etc/consul/tls/cli.pem"
    key_file  = "/etc/consul/tls/cli-key.pem"
  }
}

// node-level preflight before running Connect workloads
// CONSUL_HTTP_ADDR must be reachable, and consul version pairs with envoy version
consul members >/dev/null && echo consul-ok
consul version && envoy --version

// hook-level: the error is recoverable; emulate its retry in tooling
for i := 0; i < 5; i++ {
  err := bootstrapEnvoy()
  if err == nil || errors.Is(err, errEnvoyBootstrapError) {
    time.Sleep(time.Duration(rand.Intn(500))*time.Millisecond)
    continue
  }
  break
}

When it happens

Trigger: Prestart of the envoy bootstrap hook runs `consul connect envoy -bootstrap` (or calls the Consul xDS API) and the command exits non-zero or the API errors: Consul agent unreachable/ACL denied, Consul HTTP addr mismatch, TLS/auth problems, unsupported envoy/consul version combination, or service kind not registered yet in Consul.

Common situations: CONSUL_HTTP_ADDR unset or wrong on the node; Consul ACL token missing envoy-service permission (service:write, node:read, etc.); mTLS misconfigured between Nomad and Consul; envoy binary version not supported by the installed Consul version; Consul agent down or restarted during job deploy.

Related errors

• Service with provider nomad cannot include Connect blocks
• failed to generate envoy bootstrap config: %w
• %w: %v; see: <https://developer.hashicorp.com/nomad/s/envoy-
• missing %q
• error retrieving supported Envoy versions from Consul: %w

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