service %q defines a sidecar task in Consul Connect definiti

Error message

service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set

What it means

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.

Source

Thrown at nomad/structs/structs.go:4920

	//
	// 1. if we have a service.task configured, we need to make sure that task
	// has a shutdown_delay set.
	// 2. if it's a connect service, we look at the task we're proxying.
	// 3. if neither, at least one task should have a shutdown delay defined.
	referencedTaskIDs := map[string]struct{}{}
	hasUnscopedGroupService := false
	anyTaskHasShutdownDelay := false
	hasGroupShutdownDelay := tg.ShutdownDelay != nil && *tg.ShutdownDelay > 0

	for _, s := range tg.Services {
		if s.TaskName != "" {
			referencedTaskIDs[s.TaskName] = struct{}{}
			continue
		}

		if s.Connect != nil && s.Connect.SidecarTask != nil {
			if s.Connect.SidecarTask.ShutdownDelay == nil {
				warnings = append(warnings, fmt.Errorf(
					"service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set",
					s.Name))
			}
			continue
		}

		hasUnscopedGroupService = true
	}

	for _, t := range tg.Tasks {
		if _, ok := referencedTaskIDs[t.Name]; ok && t.ShutdownDelay == 0 {
			warnings = append(warnings, fmt.Errorf(
				"group %q references task %q in a service definition, but the task has no shutdown_delay set",
				tg.Name, t.Name))
		}

		if t.ShutdownDelay > 0 {
			anyTaskHasShutdownDelay = true

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before
service {
  name = "web"
  connect { sidecar_task { resources { cpu = 500 } } }
}
// after
service {
  name = "web"
  connect { sidecar_task { shutdown_delay = "5s" resources { cpu = 500 } } }
}

Defensive patterns

Strategy: validation

Validate before calling

for _, s := range group.Services {
    if s.Connect != nil && s.Connect.SidecarTask != nil &&
       s.Connect.SidecarTask.ShutdownDelay == nil {
        log.Warnf("service %q sidecar_task missing shutdown_delay", s.Name)
    }
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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