error interpreting desired Envoy version from Consul: %w

Error message

error interpreting desired Envoy version from Consul: %w

What it means

After fetching the supported proxies data from Consul, the hook calls tweakImage to interpolate ${NOMAD_envoy_version} in the task's configured Envoy image. If tweakImage fails (it internally runs the semver parsing), the hook wraps the error meaning Nomad could not interpret the Envoy version Consul reported.

Source

Thrown at client/allocrunner/taskrunner/envoy_version_hook.go:97

		return nil
	}

	// We either need to acquire Consul's preferred Envoy version or fallback
	// to the legacy default. Query Consul and use the (possibly empty) result.
	//
	// TODO(tgross): how do we select the right cluster here if we have multiple
	// services which could have their own cluster field value?
	proxies, err := h.proxiesClientFunc(structs.ConsulDefaultCluster).Proxies()
	if err != nil {
		return fmt.Errorf("error retrieving supported Envoy versions from Consul: %w", err)
	}

	// Second [pseudo] interpolation of task image. This determines the concrete
	// Envoy image identifier by applying version string substitution of
	// ${NOMAD_envoy_version} acquired from Consul.
	image, err := h.tweakImage(h.taskImage(request.Task.Config), proxies)
	if err != nil {
		return fmt.Errorf("error interpreting desired Envoy version from Consul: %w", err)
	}

	// Set the resulting image.
	h.logger.Trace("setting task envoy image", "image", image)
	request.Task.Config["image"] = image
	return nil
}

// interpolateImage applies the first pass of interpolation on the task's
// config.image value. This is where ${meta.connect.sidecar_image} or
// ${meta.connect.gateway_image} becomes something that might include the
// ${NOMAD_envoy_version} pseudo variable for further resolution.
func (_ *envoyVersionHook) interpolateImage(task *structs.Task, env *taskenv.TaskEnv) {
	value, exists := task.Config["image"]
	if !exists {
		return
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Inspect the wrapped %v detail to see the exact parse failure and the offending version string.
Set an explicit envoy version-supported config or pin the task image instead of relying on ${NOMAD_envoy_version}.
Ensure the Consul version reports a standard x.y.z Envoy version; upgrade Consul if it returns unexpected data.
Use an official envoy version tag format (vX.Y.Z or X.Y.Z) in your image template.
Check nomad/consul version compatibility for the connect/envoy version negotiation feature.

Example fix

// before
image = "envoyproxy/envoy:v${NOMAD_envoy_version}" // yields v:1.28.0-ish parse quirks or empty version
// after
image = "envoyproxy/envoy:${NOMAD_envoy_version}" // or pin: "envoyproxy/envoy:v1.28.0"

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/hashicorp/go-version"
// validate the image template yields a parseable version before submit
v, err := version.NewVersion("1.28.0") // value Consul is expected to report
if err != nil { return fmt.Errorf("bad envoy version: %w", err) }

Type guard

func isParseableEnvoyVersion(s string) bool {
    _, err := version.NewVersion(strings.TrimPrefix(s, "v"))
    return err == nil
}

Try / catch

err := hook.Prestart(ctx, req)
if err != nil && strings.HasPrefix(err.Error(), "error interpreting desired Envoy version") {
    // pin an explicit envoy image in the task config and resubmit
}

Prevention

Pin an explicit Envoy image instead of relying on ${NOMAD_envoy_version} when unsure.
Use official, semver-formatted Envoy tags (X.Y.Z or vX.Y.Z).
Keep Consul and Nomad versions aligned for connect version negotiation.
Test job image templates locally to confirm interpolation produces a valid version.

When it happens

Trigger: h.tweakImage(h.taskImage(request.Task.Config), proxies) returns an error in Prestart — typically because the version string returned by Consul (or derived from the image) isn't parseable as semver, e.g. it is empty, has an unexpected format, or the image template is malformed.

Common situations: Consul returns a version string the hook can't parse (unusual or missing version); job image field uses ${NOMAD_envoy_version} in a way that leaves an invalid version after interpolation; unofficial Envoy image tags not matching x.y.z; Consul/nomad version mismatch producing unexpected proxy data.

Related errors

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