nats-io/nats-server · error

unknown signal %q

Error message

unknown signal %q

What it means

CommandToSignal maps the CLI signal command (stop, quit, reopen, reload, ldm, term) to a syscall signal number; the default branch means an unrecognized Command value reached the mapper. Almost always an invalid subcommand passed to nats-server --signal (e.g. 'hup' instead of 'reload').

Source

Thrown at server/signal.go:164

}

// Translates a command to a signal number
func CommandToSignal(command Command) (syscall.Signal, error) {
	switch command {
	case CommandStop:
		return syscall.SIGKILL, nil
	case CommandQuit:
		return syscall.SIGINT, nil
	case CommandReopen:
		return syscall.SIGUSR1, nil
	case CommandReload:
		return syscall.SIGHUP, nil
	case commandLDMode:
		return syscall.SIGUSR2, nil
	case commandTerm:
		return syscall.SIGTERM, nil
	default:
		return 0, fmt.Errorf("unknown signal %q", command)
	}
}

// resolvePids returns the pids for all running nats-server processes.
func resolvePids() ([]int, error) {
	// If pgrep isn't available, this will just bail out and the user will be
	// required to specify a pid.
	output, err := pgrep()
	if err != nil {
		switch err.(type) {
		case *exec.ExitError:
			// ExitError indicates non-zero exit code, meaning no processes
			// found.
			break
		default:
			return nil, errors.New("unable to resolve pid, try providing one")
		}
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Use a supported command: stop, quit, reopen, reload, ldm, term
2. Check spelling of the value after --signal (e.g. <pid>:reload)

When it happens

Trigger: Thrown at server/signal.go:164 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/9b02db6e9ced7aa4. Report an issue: GitHub.