hashicorp/nomad · error

error unknown signal given for shutdown: %s

Error message

error unknown signal given for shutdown: %s

What it means

Shutdown looks up the configured shutdown signal (defaulting to SIGINT) in signals.SignalLookup; if the configured signal name is not recognized, it returns this error without signaling the task. The signal string comes from the driver/task config (e.g. kill_signal), so a typo or unsupported name triggers it.

Source

Thrown at drivers/shared/executor/executor.go:647

	}

	proc, err := os.FindProcess(e.childCmd.Process.Pid)
	if err != nil {
		err = fmt.Errorf("executor failed to find process: %v", err)
		e.logger.Warn("failed to shutdown due to inability to find process", "pid", e.childCmd.Process.Pid, "error", err)
		return err
	}

	// If grace is 0 then skip shutdown logic
	if grace > 0 {
		// Default signal to SIGINT if not set
		if signal == "" {
			signal = "SIGINT"
		}

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

		if err := e.shutdownProcess(sig, proc); err != nil {
			e.logger.Warn("failed to shutdown process", "pid", proc.Pid, "error", err)
			return err
		}

		select {
		case <-e.processExited:
		case <-time.After(grace):
			proc.Kill()
		}
	} else {
		proc.Kill()
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the signal name in the task config to a standard form like 'SIGINT', 'SIGTERM', 'SIGHUP'
2. Trim whitespace and match the exact casing expected by signals.SignalLookup
3. Verify the signal exists on the target platform (Windows supports only a small subset)
4. Check signals.SignalLookup in the repo for the accepted set of names

Example fix

// before (task config)
kill_signal = "sigquit "
// after
kill_signal = "SIGQUIT"

validSignals := map[string]bool{"SIGINT": true, "SIGTERM": true, "SIGHUP": true, "SIGQUIT": true, "SIGKILL": true}
sig := strings.TrimSpace(strings.ToUpper(cfg.KillSignal))
if sig == "" { sig = "SIGINT" }
if !validSignals[sig] {
    return fmt.Errorf("unsupported kill_signal %q", cfg.KillSignal)
}

func isValidSignalName(s string) bool {
    _, ok := signals.SignalLookup[strings.TrimSpace(s)]
    return ok
}

if err := exec.Shutdown(); err != nil {
    if strings.Contains(err.Error(), "unknown signal given for shutdown") {
        return fmt.Errorf("fix kill_signal in task config: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Shutdown with a driver/task kill_signal set to an unknown or misspelled name such as 'SIGTERM ' (trailing space), 'sigterm' on a platform where lookup is case-sensitive, or a signal not present in the signal map (e.g. platform-specific signals).

Common situations: Typo in task config kill_signal; copying a signal name valid on one OS to another (Windows); whitespace or casing mistakes in HCL/JSON job files.

Related errors

• executor Shutdown failed: %v
• error unknown signal given for shutdown: %s
• executor shutdown error: %v
• No nomad log file defined
• consul address must be set on nomad client

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