{"record":{"id":"5dd39673a28855f2","repo":"hashicorp/nomad","slug":"must-specify-signal-value-when-change-mode-is-sign","errorCode":null,"errorMessage":"Must specify signal value when change mode is signal","messagePattern":"Must specify signal value when change mode is signal","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/structs.go","lineNumber":8985,"sourceCode":"\t// Verify we can render somewhere\n\tif t.DestPath == \"\" {\n\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"Must specify a destination for the template\"))\n\t}\n\n\t// Verify the destination doesn't escape\n\tescaped, err := escapingfs.PathEscapesAllocViaRelative(\"task\", t.DestPath)\n\tif err != nil {\n\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"invalid destination path: %v\", err))\n\t} else if escaped {\n\t\tmErr.Errors = append(mErr.Errors, fmt.Errorf(\"destination escapes allocation directory\"))\n\t}\n\n\t// Verify a proper change mode\n\tswitch t.ChangeMode {\n\tcase TemplateChangeModeNoop, TemplateChangeModeRestart:\n\tcase TemplateChangeModeSignal:\n\t\tif t.ChangeSignal == \"\" {\n\t\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"Must specify signal value when change mode is signal\"))\n\t\t}\n\t\tif t.Envvars {\n\t\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"cannot use signals with env var templates\"))\n\t\t}\n\tcase TemplateChangeModeScript:\n\t\tif t.ChangeScript == nil {\n\t\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"must specify change script configuration value when change mode is script\"))\n\t\t}\n\n\t\tif err = t.ChangeScript.Validate(); err != nil {\n\t\t\t_ = multierror.Append(&mErr, err)\n\t\t}\n\tdefault:\n\t\t_ = multierror.Append(&mErr, TemplateChangeModeInvalidError)\n\t}\n\n\t// Verify the splay is positive\n\tif t.Splay < 0 {","sourceCodeStart":8967,"sourceCodeEnd":9003,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/structs.go#L8967-L9003","documentation":"Template.Validate() enforces that when a template's change_mode is \"signal\", a change_signal must be provided, because Nomad needs to know which signal to send to the task on template change. Empty ChangeSignal with ChangeModeSignal yields this error in the validation multierror.","triggerScenarios":"Submitting a job with template { change_mode = \"signal\" } but no change_signal set (t.ChangeSignal == \"\"). Triggered in the switch over t.ChangeMode in Template.Validate().","commonSituations":"Setting change_mode = \"signal\" copied from an example but forgetting the change_signal line; renaming the template and losing the signal field; assuming a default signal exists (there is none for signal mode).","solutions":["Add a change_signal, e.g. template { change_mode = \"signal\" change_signal = \"SIGHUP\" }.","Or switch change_mode to \"restart\" (or remove change_mode to use the default) if signaling is not needed.","Verify the chosen signal is one the task's process actually handles."],"exampleFix":"// before\ntemplate {\n  data        = \"...\"\n  destination = \"local/app.conf\"\n  change_mode = \"signal\"\n}\n// after\ntemplate {\n  data          = \"...\"\n  destination   = \"local/app.conf\"\n  change_mode   = \"signal\"\n  change_signal = \"SIGHUP\"\n}","handlingStrategy":"validation","validationCode":"// Pre-submit check\nif tpl.ChangeMode == \"signal\" && tpl.ChangeSignal == \"\" {\n  return errors.New(\"change_mode=signal requires change_signal\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set change_signal whenever change_mode = \"signal\" (commonly SIGHUP for config reloads).","Prefer change_mode = \"restart\" when no signal handler exists in the app.","Verify the app process actually handles the signal you configure."],"tags":["nomad","template","signals","job-spec-validation"],"backgroundTag":"missing-change-signal","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"}