hashicorp/nomad · error

failed to parse signal: %w

Error message

failed to parse signal: %w

What it means

signalTask parses wid.ChangeSignal with signals.Parse before sending it to the task; an invalid signal name yields 'failed to parse signal: %w'. This happens inside identity watching: when a workload identity is rotated and a change signal is configured, Nomad must translate the configured name (e.g. 'SIGHUP') into a signal value to deliver.

Source

Thrown at client/allocrunner/taskrunner/identity_hook.go:199

						SetDisplayMessage(fmt.Sprintf("Identity[%s]: failed to send signal: %v", wid.Name, err)))
					return
				}

			}

			// Note: any code added here will not run on first run

		case <-h.stopCtx.Done():
			return
		}
	}
}

// signalTask sends the configured signal to a task or returns an error.
func (h *identityHook) signalTask(wid *structs.WorkloadIdentity) error {
	s, err := signals.Parse(wid.ChangeSignal)
	if err != nil {
		return fmt.Errorf("failed to parse signal: %w", err)
	}

	event := structs.NewTaskEvent(structs.TaskSignaling).
		SetTaskSignal(s).
		SetDisplayMessage(fmt.Sprintf("Identity[%s]: new Identity token acquired", wid.Name))
	return h.lifecycle.Signal(event, wid.ChangeSignal)
}

// setDefaultToken adds the Nomad token to the task's environment and writes it to a
// file if requested by the jobsepc.
func (h *identityHook) setDefaultToken() error {
	token := h.alloc.SignedIdentities[h.task.Name]
	if token == "" {
		return nil
	}

	// Handle internal use and env var
	h.ts.setNomadToken(token)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set change_signal to a valid signal name (e.g. SIGHUP, SIGUSR1) with correct spelling and casing
2. Verify the signal is supported on the client OS (Windows supports only a subset like SIGTERM/SIGINT/SIGKILL/SIGHUP equivalents)
3. Remove or fix the identity's change_signal block if the task does not need to be notified of rotation
4. Check the wrapped %w error in the task event for the exact parse complaint

Example fix

// before
identity {
  name = "default"
  change_signal = "HUP"
}
// after
identity {
  name = "default"
  change_signal = "SIGHUP"
}

// pre-validate the configured signal name
if _, err := signals.Parse(cfg.ChangeSignal); err != nil {
    return fmt.Errorf("invalid change_signal: %v", err)
}

When it happens

Trigger: A workload identity block specifies a change_signal string that signals.Parse cannot recognize — misspelled names, lowercase/odd casing not matching known names, numbers out of range, or platform-unsupported signals

Common situations: Typo like change_signal = "SIGHUPP", using a Windows-unsupported signal on a Windows client, or copy-pasted config from another tool using different signal naming conventions

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse signal %q
• can only use change_signal=%q with change_mode=%q
• change_signal must be specified when using change_mode=%q
• file parameter must be true in order to specify filepath
• no signed workload identity available

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