hashicorp/nomad · error

invalid drain_on_shutdown config: %v

Error message

invalid drain_on_shutdown config: %v

What it means

The client.drain_on_shutdown block is converted by clientconfig.DrainConfigFromAgent; on invalid configuration (bad deadline/duration values etc.) the wrapped error is returned as this message, failing agent startup or reload.

Source

Thrown at command/agent/agent.go:1153

	for _, hn := range agentConfig.Client.HostNetworks {
		conf.HostNetworks[hn.Name] = hn
	}
	conf.BindWildcardDefaultHostNetwork = agentConfig.Client.BindWildcardDefaultHostNetwork

	if agentConfig.Client.NomadServiceDiscovery != nil {
		conf.NomadServiceDiscovery = *agentConfig.Client.NomadServiceDiscovery
	}

	artifactConfig, err := clientconfig.ArtifactConfigFromAgent(agentConfig.Client.Artifact)
	if err != nil {
		return nil, fmt.Errorf("invalid artifact config: %v", err)
	}

	conf.Artifact = artifactConfig

	drainConfig, err := clientconfig.DrainConfigFromAgent(agentConfig.Client.Drain)
	if err != nil {
		return nil, fmt.Errorf("invalid drain_on_shutdown config: %v", err)
	}
	conf.Drain = drainConfig

	conf.Users = clientconfig.UsersConfigFromAgent(agentConfig.Client.Users)

	// Iterate the fingerprinter configs and populate the client mapping. The
	// validation function returns a suitable error that can be returned without
	// formatting.
	for _, fingerprinterCfg := range agentConfig.Client.Fingerprinters {
		if err := fingerprinterCfg.Validate(); err != nil {
			return nil, err
		}
		conf.Fingerprinters[fingerprinterCfg.Name] = fingerprinterCfg
	}

	conf.LogFile = agentConfig.LogFile
	conf.DefaultIneligible = agentConfig.Client.DefaultIneligible

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the drain_on_shutdown values: durations must include units, e.g. deadline = "15m"
2. Inspect the wrapped %v error for the exact offending field
3. Verify config with `nomad agent -verify-only`
4. Consult the Nomad docs for the drain_on_shutdown schema of your version

Example fix

// before
client {
  drain_on_shutdown {
    deadline = "600"
  }
}
// after
client {
  drain_on_shutdown {
    deadline = "10m"
  }
}

if _, err := time.ParseDuration(deadline); err != nil {
    return fmt.Errorf("drain_on_shutdown deadline must be a Go duration (e.g. 15m): %w", err)
}

When it happens

Trigger: An invalid client.drain_on_shutdown stanza — e.g. drain deadline not a valid Go duration string, malformed ignore_system_jobs/healthiness options — during clientConfig build, agent start, or handleReload.

Common situations: Setting deadline = "600" instead of "600s" after upgrading Nomad (drain_on_shutdown added in Nomad 1.x), misindented HCL blocks, or invalid monitor_update_interval values.

Related errors

• failed to parse config:
• only one of cgroups_v1_override and cgroups_v2_override may
• work_dir must be an absolute path
• require only one of PemKey or PemKeyFile
• missing PemCert, PemCertFile, or KeyID

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