hashicorp/nomad · error

Invalid change mode. Must be one of the following: noop, sig

Error message

Invalid change mode. Must be one of the following: noop, signal, script, restart

What it means

TemplateChangeModeInvalidError is a package-level sentinel in nomad/structs thrown by Template.Validate() when the template's change_mode field is not one of noop, signal, script, or restart (the default switch branch of validation). Because it's a declared exported variable, tests and callers can compare against it directly.

Source

Thrown at nomad/structs/structs.go:8816

	TemplateChangeModeNoop = "noop"

	// TemplateChangeModeSignal marks that the task should be signaled if the
	// template is re-rendered
	TemplateChangeModeSignal = "signal"

	// TemplateChangeModeRestart marks that the task should be restarted if the
	// template is re-rendered
	TemplateChangeModeRestart = "restart"

	// TemplateChangeModeScript marks that the task should trigger a script if
	// the template is re-rendered
	TemplateChangeModeScript = "script"
)

var (
	// TemplateChangeModeInvalidError is the error for when an invalid change
	// mode is given
	TemplateChangeModeInvalidError = errors.New("Invalid change mode. Must be one of the following: noop, signal, script, restart")
)

// Template represents a template configuration to be rendered for a given task
type Template struct {
	// SourcePath is the path to the template to be rendered
	SourcePath string

	// DestPath is the path to where the template should be rendered
	DestPath string

	// EmbeddedTmpl store the raw template. This is useful for smaller templates
	// where they are embedded in the job file rather than sent as an artifact
	EmbeddedTmpl string

	// ChangeMode indicates what should be done if the template is re-rendered
	ChangeMode string

	// ChangeSignal is the signal that should be sent if the change mode

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set change_mode to exactly one of: noop, signal, script, restart.
2. If you want SIGHUP-style reload behavior use change_mode = "signal" together with change_signal.
3. Remove the change_mode stanza entirely to accept the default (Nomad defaults to "signal" where applicable).
4. Validate the job with `nomad job validate` to catch the typo before submission.

Example fix

// before
template {
  data        = "..."
  destination = "local/app.conf"
  change_mode = "reload"
}
// after
template {
  data          = "..."
  destination   = "local/app.conf"
  change_mode   = "signal"
  change_signal = "SIGHUP"
}

var validChangeModes = map[string]bool{"noop": true, "signal": true, "script": true, "restart": true}
func validateChangeMode(m string) error {
	if !validChangeModes[m] {
		return fmt.Errorf("invalid change_mode %q: must be noop, signal, script, or restart", m)
	}
	return nil
}

func isChangeMode(s string) bool {
	switch s {
	case "noop", "signal", "script", "restart":
		return true
	}
	return false
}

if err := job.Validate(); err != nil {
	if strings.Contains(err.Error(), "Invalid change mode") {
		// reject the template stanza with a clear message listing allowed modes
	}
	return err
}

When it happens

Trigger: Submitting a job whose template stanza sets change_mode to an unsupported string (typo like "signals", "reload", "re-sart", or a value from another tool), causing the default case in Template.Validate to append this error.

Common situations: Typo or copy-paste from Consul Template config that uses different keys; switching between Nomad versions with different accepted modes and carrying an old value; JSON job specs where change_mode was set programmatically without an enum check.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• not a valid task schedule state
• numa affinity must be one of none, prefer, or require
• All templates should have same Once value
• Failed to parse signal %q
• network address family must be one of: "", %q, %q

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