nats-io/nats-server · error

unrecognized command: %q

Error message

unrecognized command: %q

What it means

The command-line argument parser encountered a sub-command it does not recognize while processing flags like version/help. ProcessCommandLine returns this for any non-option argument that isn't 'version' or 'help'.

Source

Thrown at server/server.go:1695

// PrintServerAndExit will print our version and exit.
func PrintServerAndExit() {
	fmt.Printf("nats-server: v%s\n", VERSION)
	os.Exit(0)
}

// ProcessCommandLineArgs takes the command line arguments
// validating and setting flags for handling in case any
// sub command was present.
func ProcessCommandLineArgs(cmd *flag.FlagSet) (showVersion bool, showHelp bool, err error) {
	if len(cmd.Args()) > 0 {
		arg := cmd.Args()[0]
		switch strings.ToLower(arg) {
		case "version":
			return true, false, nil
		case "help":
			return false, true, nil
		default:
			return false, false, fmt.Errorf("unrecognized command: %q", arg)
		}
	}

	return false, false, nil
}

// Public version.
func (s *Server) Running() bool {
	return s.isRunning()
}

// Protected check on running state
func (s *Server) isRunning() bool {
	return s.running.Load()
}

func (s *Server) logPid() error {
	pidStr := strconv.Itoa(os.Getpid())

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Remove the positional argument: run `nats-server` (optionally `-c config.conf`) with no subcommand
2. Use recognized subcommands only: `nats-server version` or `nats-server help`
3. Check the exact command line in scripts/systemd units for stray args
4. Run `nats-server --help` to list valid flags

Example fix

// before
nats-server start -c nats.conf
// after
nats-server -c nats.conf

// Validate CLI args before exec
args := os.Args[1:]
for _, a := range args {
    if !strings.HasPrefix(a, "-") {
        switch strings.ToLower(a) {
        case "version", "help":
        default:
            log.Fatalf("unrecognized command: %q (nats-server takes no subcommand)", a)
        }
    }
}

if _, _, err := opts.ProcessCommandLine(args); err != nil {
    if strings.HasPrefix(err.Error(), "unrecognized command") {
        fmt.Fprintln(os.Stderr, err, "-- run 'nats-server --help'")
        os.Exit(2)
    }
    return err
}

When it happens

Trigger: Running the binary with an unexpected positional argument, e.g. `nats-server serve`, `nats-server start` (there is no 'start' subcommand — it runs by default), or a stray positional arg after flags.

Common situations: Users coming from other servers typing `nats-server start`; typos like `nats-server versio`; shell scripts appending an accidental extra argument; packaging wrappers passing a subcommand.

Related errors

• invalid signal parameters: %v
• gsl: notification already registered
• error creating store for stream
• error creating store for consumer
• JS_STREAM_OFFLINE

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