hashicorp/nomad · error

error unknown signal given for shutdown: %s

Error message

error unknown signal given for shutdown: %s

What it means

LibcontainerExecutor.Shutdown looks up the requested signal name in signals.SignalLookup. If the configured kill signal string (from the task's kill_signal or driver config) is not a known signal name, Shutdown returns this error instead of signaling the container, so the task never receives a graceful shutdown.

Source

Thrown at drivers/shared/executor/executor_linux_cgo.go:375

	status, err := l.container.Status()
	if err != nil {
		return err
	}

	defer l.container.Destroy()

	if status == libcontainer.Stopped {
		return nil
	}

	if grace > 0 {
		if signal == "" {
			signal = "SIGINT"
		}

		sig, ok := signals.SignalLookup[signal]
		if !ok {
			return fmt.Errorf("error unknown signal given for shutdown: %s", signal)
		}

		// Signal initial container processes only during graceful
		// shutdown; hence `false` arg.
		err = l.container.Signal(sig)
		if err != nil {
			return err
		}

		// nosemgrep
		select {
		case <-l.userProcExited:
			return nil
		case <-time.After(grace):
			if err := l.container.Signal(os.Kill); err != nil {
				return err
			}
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set kill_signal in the task to an exact, supported name such as "SIGTERM" or "SIGINT"
2. Check the signal table (signals.SignalLookup) for valid names supported on the target OS/arch
3. Remove any stray whitespace or custom signal aliases from the task/driver config
4. If an app needs an unusual signal, use a supported one plus an in-app handler instead

var validSignals = map[string]bool{"SIGINT": true, "SIGTERM": true, "SIGQUIT": true, "SIGHUP": true}
if !validSignals[strings.ToUpper(killSignal)] {
    return fmt.Errorf("kill_signal %q not supported; use SIGINT or SIGTERM", killSignal)
}

if err := executor.Shutdown(); err != nil && strings.Contains(err.Error(), "unknown signal given for shutdown") {
    log.Printf("bad kill_signal in task config: %v — fix job spec", err)
}

When it happens

Trigger: Shutdown called (via catchSignals on client shutdown or task Stop) with a signal string not present in signals.SignalLookup — e.g. a misspelled or unsupported kill_signal value.

Common situations: Typo in job spec kill_signal (e.g. "SIGQUIT" on a build without it, "sigterm" casing issues, or plain "TERM"); task config carrying an OS-unsupported signal name; misconfigured driver templates injecting an invalid signal value.

Related errors

• executor Shutdown failed: %v
• executor Shutdown failed: %v
• executor failed to shutdown error: no process found
• executor failed to find process: %v
• error unknown signal given for shutdown: %s

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