{"record":{"id":"bdbe855c1fce977f","repo":"hashicorp/nomad","slug":"envoy-must-be-used-as-connect-sidecar-or-gateway","errorCode":null,"errorMessage":"envoy must be used as connect sidecar or gateway","messagePattern":"envoy must be used as connect sidecar or gateway","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/envoy_bootstrap_hook.go","lineNumber":227,"sourceCode":"\tcase structs.ConnectProxyPrefix:\n\t\treturn true\n\tcase structs.ConnectIngressPrefix:\n\t\treturn true\n\tcase structs.ConnectTerminatingPrefix:\n\t\treturn true\n\tcase structs.ConnectMeshPrefix:\n\t\treturn true\n\tdefault:\n\t\treturn false\n\t}\n}\n\nfunc (_ *envoyBootstrapHook) extractNameAndKind(kind structs.TaskKind) (string, string, error) {\n\tserviceName := kind.Value()\n\tserviceKind := kind.Name()\n\n\tif !isConnectKind(serviceKind) {\n\t\treturn \"\", \"\", errors.New(\"envoy must be used as connect sidecar or gateway\")\n\t}\n\n\tif serviceName == \"\" {\n\t\treturn \"\", \"\", errors.New(\"envoy must be configured with a service name\")\n\t}\n\n\treturn serviceKind, serviceName, nil\n}\n\nfunc (h *envoyBootstrapHook) lookupService(svcKind, svcName string, taskEnv *taskenv.TaskEnv) (*structs.Service, error) {\n\ttg := h.alloc.Job.LookupTaskGroup(h.alloc.TaskGroup)\n\tinterpolatedServices := taskenv.InterpolateServices(taskEnv, tg.Services)\n\n\tvar service *structs.Service\n\tfor _, s := range interpolatedServices {\n\t\tif s.Name == svcName {\n\t\t\tservice = s\n\t\t\tbreak","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/envoy_bootstrap_hook.go#L209-L245","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","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.","Verify the service block has connect configured — envoy only bootstraps for services with a Connect stanza.","Re-validate the job (nomad job validate) after fixing; check Nomad docs for supported TaskKind values in your version."],"exampleFix":"// before\ntask \"envoy\" {\n  driver = \"docker\"\n}\n// after\nservice {\n  name = \"count-api\"\n  port = \"9001\"\n  connect { sidecar_service {} }\n}\n// (do not declare the envoy task; Nomad injects it with kind connect-proxy:count-api)","handlingStrategy":"validation","validationCode":"// validate the job spec before submitting\n// must pass, and the connect stanza must exist for any envoy sidecar\n$ nomad job validate <file>.nomad.hcl\n// in CI: fail if a task is named envoy without a proper kind\nif grep -Eq 'task\\s+\"envoy\"' job.nomad.hcl && ! grep -q 'kind\\s*=\\s*\"connect' job.nomad.hcl; then\n  echo \"envoy task missing connect kind\"; exit 1\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never hand-write envoy tasks; rely on connect.sidecar_service / sidecar_task overrides.","Use exact TaskKind strings: connect-proxy:<service>, ingress-gateway, terminating-gateway, mesh-gateway.","Run nomad job validate in CI for every job change.","Only enable envoy usage for services that declare a connect stanza."],"tags":["consul-connect","envoy","nomad","job-spec"],"backgroundTag":"invalid-task-kind","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"}