hashicorp/nomad · error

failed to parse signal: %v

Error message

failed to parse signal: %v

What it means

Before sending a signal to the container, taskHandle.Signal validates the signal string with signals.Parse (Nomad's cross-platform signal parser). If the string is not a recognized signal name (e.g. 'SIGUSR9'), the signal is never sent and this error is returned.

Source

Thrown at drivers/docker/handle.go:131

		return nil, err
	}
	defer hijacked.Close()

	execResult.Stdout = stdout.Bytes()
	execResult.Stderr = stderr.Bytes()
	res, err := h.dockerClient.ExecInspect(ctx, exec.ID, mclient.ExecInspectOptions{})
	if err != nil {
		return execResult, fmt.Errorf("failed to inspect exit code of exec object: %w", err)
	}

	execResult.ExitResult.ExitCode = res.ExitCode
	return execResult, nil
}

func (h *taskHandle) Signal(ctx context.Context, s string) error {
	_, err := signals.Parse(s)
	if err != nil {
		return fmt.Errorf("failed to parse signal: %v", err)
	}

	_, err = h.dockerClient.ContainerKill(ctx, h.containerID, mclient.ContainerKillOptions{Signal: s})
	return err
}

// parseSignal interprets the signal name into an os.Signal. If no name is
// provided, the docker driver defaults to SIGTERM. If the OS is Windows and
// SIGINT is provided, the signal is converted to SIGTERM.
func parseSignal(os, signal string) (os.Signal, error) {
	// Unlike other drivers, docker defaults to SIGTERM, aiming for consistency
	// with the 'docker stop' command.
	// https://docs.docker.com/engine/reference/commandline/stop/#extended-description
	if signal == "" {
		signal = "SIGTERM"
	}

	// Windows Docker daemon does not support SIGINT, SIGTERM is the semantic equivalent that

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use a canonical signal name supported by Nomad, e.g. 'SIGTERM', 'SIGHUP', 'SIGUSR1'.
2. Fix the task's kill_signal field in the job spec and redeploy.
3. Check the signal you pass to 'nomad alloc signal' against Nomad's documented signal list.

Example fix

// before (job hcl)
kill_signal = "TERM15"
// after
kill_signal = "SIGTERM"

var validSignals = map[string]bool{
    "SIGABRT": true, "SIGALRM": true, "SIGFPE": true, "SIGHUP": true,
    "SIGILL": true, "SIGINT": true, "SIGIO": true, "SIGKILL": true,
    "SIGPIPE": true, "SIGQUIT": true, "SIGSEGV": true, "SIGTERM": true,
    "SIGUSR1": true, "SIGUSR2": true,
}
if !validSignals[s] {
    return fmt.Errorf("unsupported signal %q", s)
}

When it happens

Trigger: The 'signal' parameter passed to the driver's Signal API (from a task's kill_signal, template change_mode signal, or nomad alloc signal command) is not a valid signal name for signals.Parse, such as 'USR1' without a recognized prefix form or a completely unknown name.

Common situations: Typo in the job spec's kill_signal; using a numeric signal ('9') where the parser expects names; using a Windows-incompatible signal; custom scripts calling nomad alloc signal with an invalid value.

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 signal container %q while killing: %v
• missing secret ID
• errMissingACLRoleID
• errMissingACLAuthMethodName
• errMissingACLBindingRuleID

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