{"record":{"id":"8560c8b68bad81fd","repo":"hashicorp/nomad","slug":"error-retrieving-supported-envoy-versions-from-con","errorCode":null,"errorMessage":"error retrieving supported Envoy versions from Consul: %w","messagePattern":"error retrieving supported Envoy versions from Consul: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/envoy_version_hook.go","lineNumber":89,"sourceCode":"\t// but could be a no-op or some other value if so configured.\n\th.interpolateImage(request.Task, request.TaskEnv)\n\n\t// Detect whether this hook needs to run and return early if not. Only run if:\n\t// - task uses docker driver\n\t// - task is a connect sidecar or gateway\n\t// - task image needs ${NOMAD_envoy_version} resolved\n\tif h.skip(request) {\n\t\treturn nil\n\t}\n\n\t// We either need to acquire Consul's preferred Envoy version or fallback\n\t// to the legacy default. Query Consul and use the (possibly empty) result.\n\t//\n\t// TODO(tgross): how do we select the right cluster here if we have multiple\n\t// services which could have their own cluster field value?\n\tproxies, err := h.proxiesClientFunc(structs.ConsulDefaultCluster).Proxies()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error retrieving supported Envoy versions from Consul: %w\", err)\n\t}\n\n\t// Second [pseudo] interpolation of task image. This determines the concrete\n\t// Envoy image identifier by applying version string substitution of\n\t// ${NOMAD_envoy_version} acquired from Consul.\n\timage, err := h.tweakImage(h.taskImage(request.Task.Config), proxies)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error interpreting desired Envoy version from Consul: %w\", err)\n\t}\n\n\t// Set the resulting image.\n\th.logger.Trace(\"setting task envoy image\", \"image\", image)\n\trequest.Task.Config[\"image\"] = image\n\treturn nil\n}\n\n// interpolateImage applies the first pass of interpolation on the task's\n// config.image value. This is where ${meta.connect.sidecar_image} or","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/envoy_version_hook.go#L71-L107","documentation":"The envoy_version_hook Prestart queries Consul's local agent API (via proxiesClientFunc) to get the list of Envoy versions the Consul version supports. If that Proxies() call fails, the hook cannot determine which Envoy image to use and wraps the error. The caller may treat Consul API transport/HTTP errors as recoverable and retry.","triggerScenarios":"h.proxiesClientFunc(structs.ConsulDefaultCluster).Proxies() returns an error in Prestart — Consul agent unreachable, API endpoint unsupported (older Consul without /agent/proxies), ACL denied, or HTTP 5xx.","commonSituations":"Consul agent not running or network blocked; Consul version older than the supported-proxies endpoint; Consul ACL token lacking agent read permissions; transient network flaps during task start.","solutions":["Verify the Consul agent is healthy and reachable from the Nomad client (consul members, curl the agent API).","Upgrade Consul to a version that supports the local agent proxies endpoint if you see 404.","Check the Consul ACL token's agent/service read permissions.","If the error is recoverable, rely on Nomad's retry/restart; otherwise fix connectivity and reschedule the task."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// verify Consul agent API reachability before Prestart\nresp, err := http.Get(\"http://\" + consulHTTPAddr + \"/v1/agent/self\")\nif err != nil { return err }\nif resp.StatusCode != 200 { return fmt.Errorf(\"consul agent API returned %d\", resp.StatusCode) }","typeGuard":null,"tryCatchPattern":"err := hook.Prestart(ctx, req)\nvar rec *structs.RecoverableError\nif err != nil && errors.As(err, &rec) && rec.IsRecoverable() {\n    // transient Consul/network issue: retry with backoff\n} else if err != nil {\n    // check Consul version/ACLs; the proxies endpoint may be unsupported\n}","preventionTips":["Run a Consul version that supports the supported-proxies endpoint used by Nomad.","Monitor Consul agent health from all Nomad clients.","Grant the Consul token agent-read ACL permissions.","Allow Nomad's recoverable-error retry to absorb transient Consul flaps."],"tags":["nomad","consul","envoy","network","api"],"backgroundTag":"consul-api-unreachable","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"}