{"record":{"id":"04cf69ac8b61e174","repo":"hashicorp/nomad","slug":"failed-to-parse-signal-w-04cf69","errorCode":null,"errorMessage":"failed to parse signal: %w","messagePattern":"failed to parse signal: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/vault_hook.go","lineNumber":271,"sourceCode":"\t}\n}\n\n// handleRenewalFailure attempts to get a new Vault token and triggers any change_mode\nfunc (h *vaultHook) handleRenewalFailure(ctx context.Context) (string, time.Duration, error) {\n\ttoken, duration, err := h.deriveVaultToken(ctx)\n\tif err != nil {\n\t\treturn \"\", 0, err\n\t}\n\tif err := h.writeToken(token); err != nil {\n\t\treturn \"\", 0, fmt.Errorf(\"failed to write Vault token to disk: %w\", err)\n\t}\n\n\tvar event *structs.TaskEvent\n\tswitch h.vaultBlock.ChangeMode {\n\tcase structs.VaultChangeModeSignal:\n\t\ts, err := signals.Parse(h.vaultBlock.ChangeSignal)\n\t\tif err != nil {\n\t\t\treturn \"\", 0, fmt.Errorf(\"failed to parse signal: %w\", err)\n\t\t}\n\n\t\tevent := structs.NewTaskEvent(structs.TaskSignaling).\n\t\t\tSetTaskSignal(s).SetDisplayMessage(\"Vault: new Vault token acquired\")\n\t\tif err := h.lifecycle.Signal(event, h.vaultBlock.ChangeSignal); err != nil {\n\t\t\treturn \"\", 0, fmt.Errorf(\"failed to send signal: %w\", err)\n\t\t}\n\tcase structs.VaultChangeModeRestart:\n\t\tevent = structs.NewTaskEvent(structs.TaskRestartSignal).\n\t\t\tSetDisplayMessage(\"Vault: new Vault token acquired\")\n\t\th.lifecycle.Restart(ctx, event, false)\n\tcase structs.VaultChangeModeNoop:\n\t\t// True to its name, this is a noop!\n\tdefault:\n\t\th.logger.Error(\"invalid Vault change mode\", \"mode\", h.vaultBlock.ChangeMode)\n\t}\n\n\th.updater.updatedVaultToken(token)","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/vault_hook.go#L253-L289","documentation":"In Nomad's vault_hook, when a Vault token is renewed and the vault block's change_mode is \"signal\", the hook parses the configured change_signal via signals.Parse before signaling the task. If the signal string is not a recognized signal name (e.g. on Linux \"SIGUSR1\", \"USR1\", or \"HUP\"), this wrapped error is returned and the token-change handling fails, preventing the task from receiving the new Vault token notification.","triggerScenarios":"A job's vault block sets change_mode = \"signal\" with a change_signal value that signals.Parse cannot resolve (typo like \"SIGNUSR1\", unsupported name on the platform, or empty string). The error surfaces from handleRenewalFailure when a renewed token must be delivered to the task.","commonSituations":"Typo in change_signal in the job HCL; using a Windows-only or Linux-only signal on the other OS; copy-pasting a signal name with an incorrect prefix; Nomad agent running on an OS whose signal table lacks the requested signal.","solutions":["Fix change_signal in the job's vault block to a valid signal name for the target OS (e.g. \"SIGUSR1\" or \"SIGHUP\")","Run nomad job validate/plan locally to catch invalid signal names before submission","If the task cannot handle signals, switch change_mode to \"restart\" or \"noop\" instead of \"signal\"","Check signals.Parse / signals.ValidSignals for the platform to confirm the exact accepted spelling"],"exampleFix":"// before\nvault {\n  change_mode   = \"signal\"\n  change_signal = \"SIGUSR\"\n}\n// after\nvault {\n  change_mode   = \"signal\"\n  change_signal = \"SIGUSR1\"\n}","handlingStrategy":"validation","validationCode":"// validate job before submit\n$ nomad job validate job.nomad.hcl\n// ensure signal is valid for the target platform:\n// linux: SIGUSR1, SIGHUP, ... windows: 1.0 (only '1.0'/'TERM' style) per docs","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `nomad job validate` on every job before submission","Keep a per-OS allowlist of signals your tasks can handle","Prefer change_mode = \"restart\" unless the task explicitly handles the signal","Lint job HCL in CI to catch typos in change_signal"],"tags":["nomad","vault","signal","config"],"backgroundTag":"invalid-signal-name","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"}