nats-io/nats-server · error

invalid signal parameters: %v

Error message

invalid signal parameters: %v

What it means

The NATS server signal (nats-server -s/-signal) parsing accepts signal=pid or signal=pidfile with at most one '=' separator. If the argument splits into more than two parts (multiple '=' signs), the extra parameters are invalid and this error lists them.

Source

Thrown at server/opts.go:6570

	} else {
		// Since we override from flag and there is no user/pwd, make
		// sure we clear what we may have gotten from config file.
		opts.Cluster.Username = _EMPTY_
		opts.Cluster.Password = _EMPTY_
	}

	return nil
}

func processSignal(signal string) error {
	var (
		pid           string
		commandAndPid = strings.Split(signal, "=")
	)
	if l := len(commandAndPid); l == 2 {
		pid = maybeReadPidFile(commandAndPid[1])
	} else if l > 2 {
		return fmt.Errorf("invalid signal parameters: %v", commandAndPid[2:])
	}
	if err := ProcessSignal(Command(commandAndPid[0]), pid); err != nil {
		return err
	}
	os.Exit(0)
	return nil
}

// maybeReadPidFile returns a PID or Windows service name obtained via the following method:
// 1. Try to open a file with path "pidStr" (absolute or relative).
// 2. If such a file exists and can be read, return its contents.
// 3. Otherwise, return the original "pidStr" string.
func maybeReadPidFile(pidStr string) string {
	if b, err := os.ReadFile(pidStr); err == nil {
		return string(b)
	}
	return pidStr
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Use the form `nats-server -s stop=<pid>` (exactly one '=').
2. Remove any extra '=...' segments from the signal argument.
3. Quote the argument in the shell if it contains special characters.
4. To signal by pid file, use stop=/path/to/pidfile with a single '='.

Example fix

// before
nats-server -s reload=1234=extra
// after
nats-server -s reload=1234

// Validate the -s argument format before invoking
sig="$1"
parts=$(echo "$sig" | awk -F= '{print NF-1}')
if [ "$parts" -gt 1 ]; then echo "signal arg must be signal=<pid|pidfile>"; exit 1; fi

func isValidSignalArg(s string) bool {
    parts := strings.Split(s, "=")
    return len(parts) == 1 || len(parts) == 2
}

if err := ProcessSignalArg(signalArg); err != nil {
    return fmt.Errorf("bad -s argument %q: use stop|quit|reload=<pid|pidfile>", signalArg)
}

When it happens

Trigger: Passing a -s/--signal argument like `stop=123=456` or a value containing multiple '=' characters so strings.Split yields >2 elements.

Common situations: Shell quoting mistakes producing duplicated arguments glued with '=', copy-paste of 'reload=pid' with an extra suffix, or scripting that appends an unintended '=value'.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• unrecognized command: %q
• must specify [-c, --config] option to check configuration fi

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