{"record":{"id":"71cf578e77e99341","repo":"hashicorp/nomad","slug":"w-v-see-https-developer-hashicorp-com-noma","errorCode":null,"errorMessage":"%w: %v; see: <https://developer.hashicorp.com/nomad/s/envoy-bootstrap-error>","messagePattern":"%w: (.+?); see: <https://developer\\.hashicorp\\.com/nomad/s/envoy-bootstrap-error>","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/envoy_bootstrap_hook.go","lineNumber":413,"sourceCode":"\t\t}\n\n\t\t// Command failed, prepare for retry\n\t\t//\n\t\t// Cleanup the bootstrap file. An errors here is not\n\t\t// important as (a) we test to ensure the deletion\n\t\t// occurs, and (b) the file will either be rewritten on\n\t\t// retry or eventually garbage collected if the task\n\t\t// fails.\n\t\t_ = os.Remove(bootstrapFilePath)\n\n\t\treturn true, cmdErr\n\t}, backoffOpts)\n\n\tif backoffErr != nil {\n\t\t// Wrap the last error from Consul and set that as our status.\n\t\t_, recoverable := cmdErr.(*exec.ExitError)\n\t\treturn structs.NewRecoverableError(\n\t\t\tfmt.Errorf(\"%w: %v; see: <https://developer.hashicorp.com/nomad/s/envoy-bootstrap-error>\",\n\t\t\t\terrEnvoyBootstrapError,\n\t\t\t\tcmdErr,\n\t\t\t),\n\t\t\trecoverable,\n\t\t)\n\t}\n\n\treturn nil\n}\n\nfunc (h *envoyBootstrapHook) groupEnv() []string {\n\treturn []string{\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.AllocID, h.alloc.ID),\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.ShortAllocID, h.alloc.ID[:8]),\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.AllocName, h.alloc.Name),\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.GroupName, h.alloc.TaskGroup),\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.JobName, h.alloc.Job.Name),\n\t\tfmt.Sprintf(\"%s=%s\", taskenv.JobID, h.alloc.Job.ID),","sourceCodeStart":395,"sourceCodeEnd":431,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/envoy_bootstrap_hook.go#L395-L431","documentation":"After the backoff.Retry loop exhausts all attempts to run `consul envoy bootstrap`, the hook wraps the last cmdErr with errEnvoyBootstrapError and a link to the Nomad docs. It is a recoverable error when the failure was an exec.ExitError (non-zero exit from the consul binary), so the task will be restarted and Prestart retried.","triggerScenarios":"All backoff attempts of cmd.Run() for `consul envoy bootstrap` fail in Prestart — e.g. the consul binary is missing (exec.ErrNotFound), exits non-zero (bad config, unreachable Consul agent), or the context is cancelled repeatedly.","commonSituations":"Consul agent not running or unreachable on the client; consul binary absent from PATH inside the task environment; invalid service/connect configuration (missing sidecar service, wrong namespace/ACLs); Consul ACL token lacking permissions to register the proxy.","solutions":["Open the referenced https://developer.hashicorp.com/nomad/s/envoy-bootstrap-error page and the alloc/logs/envoy_bootstrap.stderr.N file for the underlying consul error.","Verify the Consul agent is running and reachable from the Nomad client.","Confirm the `consul` binary exists and is in PATH for the task driver environment.","Check Consul ACL token permissions (service:register, mesh ops) and service stanza correctness.","If recoverable, Nomad restarts the task automatically; fix the underlying Consul issue to stop the restart loop."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// preflight before starting connect tasks\nif _, err := exec.LookPath(\"consul\"); err != nil { return fmt.Errorf(\"consul binary missing: %w\", err) }\nif err := consulAgentReachable(); err != nil { return fmt.Errorf(\"consul agent unreachable: %w\", err) }","typeGuard":"func isEnvoyBootstrapError(err error) bool {\n    return errors.Is(err, errEnvoyBootstrapError)\n}","tryCatchPattern":"err := hook.Prestart(ctx, req)\nif errors.Is(err, errEnvoyBootstrapError) {\n    // read alloc/logs/envoy_bootstrap.stderr.N for the real consul failure\n    var rec *structs.RecoverableError\n    if errors.As(err, &rec) && rec.IsRecoverable() { /* retry with backoff */ }\n}","preventionTips":["Keep the consul binary in the task PATH and version-compatible with the Consul agents.","Monitor Consul agent health from every Nomad client.","Grant the Consul ACL token the permissions needed to bootstrap proxies.","Read the Nomad envoy-bootstrap-error docs page linked in the message first."],"tags":["nomad","consul","envoy","exec","retry"],"backgroundTag":"envoy-bootstrap-failed","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"}