{"record":{"id":"dbe03a8b6e1d79c1","repo":"hashicorp/nomad","slug":"service-q-defines-a-sidecar-task-in-consul-connec","errorCode":null,"errorMessage":"service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set","messagePattern":"service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"nomad/structs/structs.go","lineNumber":4920,"sourceCode":"\t//\n\t// 1. if we have a service.task configured, we need to make sure that task\n\t// has a shutdown_delay set.\n\t// 2. if it's a connect service, we look at the task we're proxying.\n\t// 3. if neither, at least one task should have a shutdown delay defined.\n\treferencedTaskIDs := map[string]struct{}{}\n\thasUnscopedGroupService := false\n\tanyTaskHasShutdownDelay := false\n\thasGroupShutdownDelay := tg.ShutdownDelay != nil && *tg.ShutdownDelay > 0\n\n\tfor _, s := range tg.Services {\n\t\tif s.TaskName != \"\" {\n\t\t\treferencedTaskIDs[s.TaskName] = struct{}{}\n\t\t\tcontinue\n\t\t}\n\n\t\tif s.Connect != nil && s.Connect.SidecarTask != nil {\n\t\t\tif s.Connect.SidecarTask.ShutdownDelay == nil {\n\t\t\t\twarnings = append(warnings, fmt.Errorf(\n\t\t\t\t\t\"service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set\",\n\t\t\t\t\ts.Name))\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\n\t\thasUnscopedGroupService = true\n\t}\n\n\tfor _, t := range tg.Tasks {\n\t\tif _, ok := referencedTaskIDs[t.Name]; ok && t.ShutdownDelay == 0 {\n\t\t\twarnings = append(warnings, fmt.Errorf(\n\t\t\t\t\"group %q references task %q in a service definition, but the task has no shutdown_delay set\",\n\t\t\t\ttg.Name, t.Name))\n\t\t}\n\n\t\tif t.ShutdownDelay > 0 {\n\t\t\tanyTaskHasShutdownDelay = true","sourceCodeStart":4902,"sourceCodeEnd":4938,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/structs.go#L4902-L4938","documentation":"This is a warning (not a hard error) emitted by TaskGroup.Warnings / generateServiceShutdownDelayWarnings. When a service's Consul Connect definition explicitly defines a SidecarTask, Nomad expects that sidecar task to set shutdown_delay so in-flight connections drain before the sidecar exits; if SidecarTask.ShutdownDelay is nil the warning is appended.","triggerScenarios":"Validating a job where a service stanza has `connect { sidecar_task { ... } }` but the sidecar_task block does not set `shutdown_delay`. Surfaced via `nomad job run`/`validate` warning output (Meta.FormatWarnings).","commonSituations":"Customizing the envoy sidecar (resources, args) and forgetting shutdown_delay; upgrading from configs written before shutdown_delay existed; zero-downtime deployments losing connections during sidecar restart.","solutions":["Add `shutdown_delay = \"5s\"` (or appropriate duration) inside the sidecar_task block.","Or omit the custom sidecar_task block so defaults apply, if customization is unnecessary.","Treat the warning output from `nomad job validate` as the checklist before deploying."],"exampleFix":"// before\nservice {\n  name = \"web\"\n  connect { sidecar_task { resources { cpu = 500 } } }\n}\n// after\nservice {\n  name = \"web\"\n  connect { sidecar_task { shutdown_delay = \"5s\" resources { cpu = 500 } } }\n}","handlingStrategy":"validation","validationCode":"for _, s := range group.Services {\n    if s.Connect != nil && s.Connect.SidecarTask != nil &&\n       s.Connect.SidecarTask.ShutdownDelay == nil {\n        log.Warnf(\"service %q sidecar_task missing shutdown_delay\", s.Name)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever customizing sidecar_task, always include shutdown_delay.","Treat `nomad job validate` warnings as release blockers for connect workloads.","Adopt a house job template with shutdown_delay defaults."],"tags":["nomad","consul-connect","sidecar","shutdown-delay"],"backgroundTag":"missing-shutdown-delay","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"}