hashicorp/nomad · error

invalid change_mode: %s

Error message

invalid change_mode: %s

What it means

WorkloadIdentity.Validate rejects any ChangeMode value it does not recognize. Only "restart", "signal" (and empty, meaning default) are accepted. This catches typos or modes from newer/older Nomad versions that the validating binary does not understand.

Source

Thrown at nomad/structs/workload_id.go:482

		if aud == "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("an empty string is an invalid audience (%d)", i+1))
		}
	}

	switch wi.ChangeMode {
	case "", WIChangeModeNoop, WIChangeModeRestart:
		// Treat "" as noop. Make sure signal isn't set.
		if wi.ChangeSignal != "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("can only use change_signal=%q with change_mode=%q",
				wi.ChangeSignal, WIChangeModeSignal))
		}
	case WIChangeModeSignal:
		if wi.ChangeSignal == "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("change_signal must be specified when using change_mode=%q", WIChangeModeSignal))
		}
	default:
		// Unknown change_mode
		mErr.Errors = append(mErr.Errors, fmt.Errorf("invalid change_mode: %s", wi.ChangeMode))
	}

	if wi.TTL > 0 && (wi.Name == "" || wi.Name == WorkloadIdentityDefaultName) {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("ttl for default identity not yet supported"))
	}

	if wi.TTL < 0 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("ttl must be >= 0"))
	}

	if wi.Filepath != "" && !wi.File {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("file parameter must be true in order to specify filepath"))
	}

	return mErr.ErrorOrNil()
}

func (wi *WorkloadIdentity) Warnings() error {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set change_mode to one of the supported values: "restart", "signal", or omit it for the default.
2. Fix any spelling of the change_mode value in the job spec.
3. If using a newer mode, upgrade the Nomad agent/CLI doing validation to a version that supports it.

Example fix

// before
identity {
  name = "aws"
  change_mode = "signals"
}
// after
identity {
  name = "aws"
  change_mode = "signal"
  change_signal = "SIGHUP"
}

var validChangeModes = map[string]bool{"": true, structs.WIChangeModeRestart: true, structs.WIChangeModeSignal: true}
func validateChangeMode(mode string) error {
  if !validChangeModes[mode] {
    return fmt.Errorf("change_mode %q not supported", mode)
  }
  return nil
}

When it happens

Trigger: Setting change_mode in an identity block to a misspelled or unsupported string (e.g. "signals", "rollover", "none") so it matches neither WIChangeModeRestart nor WIChangeModeSignal and falls into the default branch of Validate().

Common situations: Typo in job HCL change_mode value; running an older Nomad agent that lacks a newer change_mode introduced later; generating job JSON programmatically with a bad constant.

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

• no identities to sign
• no identities requested
• invalid KeySource %q
• unsupported bind type: %q
• Service identity must provide at least one target aud value

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