nats-io/nats-server · error

solicited routes require cluster capabilities, e.g. --cluste

Error message

solicited routes require cluster capabilities, e.g. --cluster

What it means

Startup options processing: route URLs (routes / --routes) were configured but no cluster listener exists (empty cluster listen string, host, and port), so solicited routes have no cluster to join. The routes option without cluster capabilities is the misconfiguration.

Source

Thrown at server/opts.go:6470

		}
	})
	if flagErr != nil {
		return nil, flagErr
	}

	// This will be true if some of the `-tls` params have been set and
	// `-tls=false` has not been set.
	if tlsOverride {
		if err := overrideTLS(opts); err != nil {
			return nil, err
		}
	}

	// If we don't have cluster defined in the configuration
	// file and no cluster listen string override, but we do
	// have a routes override, we need to report misconfiguration.
	if opts.RoutesStr != _EMPTY_ && opts.Cluster.ListenStr == _EMPTY_ && opts.Cluster.Host == _EMPTY_ && opts.Cluster.Port == 0 {
		return nil, errors.New("solicited routes require cluster capabilities, e.g. --cluster")
	}

	return opts, nil
}

func normalizeBasePath(p string) string {
	if len(p) == 0 {
		return "/"
	}
	// add leading slash
	if p[0] != '/' {
		p = "/" + p
	}
	return path.Clean(p)
}

// overrideTLS is called when at least "-tls=true" has been set.
func overrideTLS(opts *Options) error {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add a cluster block, e.g. --cluster or cluster { listen: 0.0.0.0:6222 }
2. Remove the routes if clustering was not intended
3. Verify the cluster listen address/port are not being overridden to empty

When it happens

Trigger: Thrown at server/opts.go:6470 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/d50a3ab7a56b367b. Report an issue: GitHub.