hashicorp/nomad · error

envoy must be used as connect sidecar or gateway

Error message

envoy must be used as connect sidecar or gateway

What it means

Raised by extractNameAndKind in the envoy bootstrap hook when the task's kind is not a recognized Connect kind — the task is configured to run envoy but its kind string is not one of the connect sidecar/gateway kinds (connect-proxy, connect-native, ingress-gateway, terminating-gateway, mesh-gateway). The hook refuses to bootstrap envoy for arbitrary tasks so the task fails during Prestart.

Source

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

	case structs.ConnectProxyPrefix:
		return true
	case structs.ConnectIngressPrefix:
		return true
	case structs.ConnectTerminatingPrefix:
		return true
	case structs.ConnectMeshPrefix:
		return true
	default:
		return false
	}
}

func (_ *envoyBootstrapHook) extractNameAndKind(kind structs.TaskKind) (string, string, error) {
	serviceName := kind.Value()
	serviceKind := kind.Name()

	if !isConnectKind(serviceKind) {
		return "", "", errors.New("envoy must be used as connect sidecar or gateway")
	}

	if serviceName == "" {
		return "", "", errors.New("envoy must be configured with a service name")
	}

	return serviceKind, serviceName, nil
}

func (h *envoyBootstrapHook) lookupService(svcKind, svcName string, taskEnv *taskenv.TaskEnv) (*structs.Service, error) {
	tg := h.alloc.Job.LookupTaskGroup(h.alloc.TaskGroup)
	interpolatedServices := taskenv.InterpolateServices(taskEnv, tg.Services)

	var service *structs.Service
	for _, s := range interpolatedServices {
		if s.Name == svcName {
			service = s
			break

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the manually-defined envoy task and use connect { sidecar_service {} } in the service block so Nomad injects the proxy task with the correct kind automatically.
2. If defining the kind explicitly, set the exact format kind = "connect-proxy:<service-name>" (or the proper gateway kind: ingress-gateway, terminating-gateway, mesh-gateway) on the task.
3. Verify the service block has connect configured — envoy only bootstraps for services with a Connect stanza.
4. Re-validate the job (nomad job validate) after fixing; check Nomad docs for supported TaskKind values in your version.

Example fix

// before
task "envoy" {
  driver = "docker"
}
// after
service {
  name = "count-api"
  port = "9001"
  connect { sidecar_service {} }
}
// (do not declare the envoy task; Nomad injects it with kind connect-proxy:count-api)

// validate the job spec before submitting
// must pass, and the connect stanza must exist for any envoy sidecar
$ nomad job validate <file>.nomad.hcl
// in CI: fail if a task is named envoy without a proper kind
if grep -Eq 'task\s+"envoy"' job.nomad.hcl && ! grep -q 'kind\s*=\s*"connect' job.nomad.hcl; then
  echo "envoy task missing connect kind"; exit 1
fi

When it happens

Trigger: A task group defines a task literally named/kind envoy (e.g. task "envoy") without kind = "connect-proxy:..." or a connect gateway kind, and Connect is enabled in the job; Prestart calls extractNameAndKind(kind) which fails isConnectKind(serviceKind).

Common situations: Job author manually adds an envoy task (copying old templates) instead of letting Nomad inject the sidecar via sidecar_task / sidecar_service; typo in the kind string (e.g. "connectproxy:svc" or "connect-proxy" missing the service suffix); trying to run envoy for a non-connect service; version drift where an old job spec kind naming is no longer accepted.

Related errors

• failed to generate envoy bootstrap config: %w
• error creating bootstrap configuration for Connect proxy sid
• ErrConnectRequireOneNetwork
• ErrConnectInvalidNetworkMode
• service.port must be set for mesh gateway service

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