What causes "missing %q" in hashicorp/nomad?

Verify the service and its connect sidecar are actually registered in Consul (consul services / UI) in the correct namespace/partition.

hashicorp/nomad · error

missing %q

Error message

missing %q

What it means

During the service preflight check, the hook repeatedly queries the Consul catalog/API to confirm the proxy's service ID is registered before bootstrapping Envoy. If the check closure never observes proxyServiceID (and never returns false early), it ends with this 'missing %q' error naming the proxy service ID, and the surrounding backoff retries until exhausted.

Source

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

			return false, nil
		default:
		}

		allocServices, apiErr = h.consulServices.AllocRegistrations(h.alloc.ID)
		if apiErr != nil {
			return true, apiErr
		}

		if allocServices != nil {
			for _, taskServices := range allocServices.Tasks {
				for id := range taskServices.Services {
					if id == proxyServiceID {
						return false, nil
					}
				}
			}
		}
		apiErr = fmt.Errorf("missing %q", proxyServiceID)
		return true, apiErr
	}, backoffOpts)

	// Wrap the last error we saw set that as our status.
	if backoffErr != nil {
		return structs.NewRecoverableError(
			fmt.Errorf("%w: %v; see: <https://developer.hashicorp.com/nomad/s/envoy-bootstrap-error>",
				errEnvoyBootstrapError,
				apiErr,
			),
			true)
	}

	return nil
}

func durationFromMeta(node *structs.Node, key string, defaultDur time.Duration) time.Duration {
	val := node.Meta[key]

View on GitHub (pinned to 482b49bf1a)

Solutions

Verify the service and its connect sidecar are actually registered in Consul (consul services / UI) in the correct namespace/partition.
Check the Consul ACL token used by Nomad has read access to the right namespace and services.
Increase patience via Consul health/registration settings or check for deregistration (e.g. Consul agents restarting, TTL checks failing).
Inspect agent logs around the recovery deadline; the wrapped error at the call site is recoverable and Nomad will retry/restart.

Defensive patterns

Strategy: retry

Validate before calling

// confirm the proxy registration is visible in Consul before bootstrapping
entries, _, err := consul.Catalog().Service(proxyServiceName, "", nil)
if err != nil || len(entries) == 0 {
    return fmt.Errorf("proxy %s not registered yet", proxyServiceID)
}

Try / catch

err := hook.Prestart(ctx, req)
if err != nil && strings.Contains(err.Error(), "missing") {
    // poll Consul catalog until the proxy ID appears, then reschedule
}

Prevention

Give Consul time to converge; rely on the hook's backoff rather than immediate restarts.
Use correct namespace/partition in job service stanzas so registrations land where the hook looks.
Ensure the Consul ACL token can read services in the target namespace.
Monitor Consul deregistration events (agent restarts, TTL failures).

When it happens

Trigger: Consul's API returns the list of service registrations but the expected proxyServiceID (the connect proxy for the task's service) is absent — e.g. registration is delayed, was deregistered, or the service was never registered due to an ACL/namespace mismatch.

Common situations: Slow Consul convergence right after task start (retries usually absorb it); Consul ACL token cannot see the service in the queried namespace/partition; the connect sidecar service is misconfigured or deregistered; multi-namespace/multi-partition setups where the hook queries the wrong namespace.

Related errors

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