nats-io/nats-server · error

duplicate server name

Error message

duplicate server name

What it means

ErrDuplicateServerName is returned when processing a server remote connection and the remote reports that this server name is already used in the cluster. NATS cluster and gateway protocols rely on unique server names, so when a remote peer sees the same name twice it rejects the connection with this sentinel error. It is exported from server/errors.go so callers can compare with errors.Is.

Source

Thrown at server/errors.go:217

	// ErrClusterNameReserved signals that the cluster name is reserved for internal protocol use.
	ErrClusterNameReserved = errors.New("cluster name is reserved")

	// ErrMalformedSubject is returned when a subscription is made with a subject that does not conform to subject rules.
	ErrMalformedSubject = errors.New("malformed subject")

	// ErrSubscribePermissionViolation is returned when processing of a subscription fails due to permissions.
	ErrSubscribePermissionViolation = errors.New("subscribe permission violation")

	// ErrNoTransforms signals no subject transforms are available to map this subject.
	ErrNoTransforms = errors.New("no matching transforms available")

	// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it
	ErrCertNotPinned = errors.New("certificate not pinned")

	// ErrDuplicateServerName is returned when processing a server remote connection and
	// the server reports that this server name is already used in the cluster.
	ErrDuplicateServerName = errors.New("duplicate server name")

	// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.
	ErrMinimumVersionRequired = errors.New("minimum version required")
	// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used
	// when rejecting a remote due to leafnodes.min_version.
	ErrLeafNodeMinVersionRejected = errors.New("connection rejected since minimum version required is")

	// ErrInvalidMappingDestination is used for all subject mapping destination errors
	ErrInvalidMappingDestination = errors.New("invalid mapping destination")

	// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping
	ErrInvalidMappingDestinationSubject = fmt.Errorf("%w: invalid transform", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards
	ErrMappingDestinationNotUsingAllWildcards = fmt.Errorf("%w: not using all of the token wildcard(s)", ErrInvalidMappingDestination)

	// ErrUnknownMappingDestinationFunction is returned when a subject mapping destination contains an unknown mustache-escaped mapping function.
	ErrUnknownMappingDestinationFunction = fmt.Errorf("%w: unknown function", ErrInvalidMappingDestination)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set a unique server name for each server in the cluster (e.g. server_name: "nats-1") and restart the offending server.
2. If no server_name is set, derive a unique name from hostname/IP instead of reusing a static value.
3. Check for stale/ghost connections or lingering processes of the same server and shut them down.

Example fix

// before
echo 'server_name: "nats"' > /etc/nats/nats-a.cfg
cp /etc/nats/nats-a.cfg /etc/nats/nats-b.cfg
// after
cat > /etc/nats/nats-b.cfg <<'EOF'
server_name: "nats-b"
EOF

if serverName == "" || duplicateInCluster(serverName) {
    return errors.New("choose a unique server_name before joining the cluster")
}

if errors.Is(err, server.ErrDuplicateServerName) {
    log.Fatalf("server name already in use: pick a unique server_name")
}

When it happens

Trigger: A solicited remote server connection (cluster or gateway) is accepted, but the remote side already has a connection registered under the same server name; the remote replies with a duplicate-name protocol error and the local side surfaces ErrDuplicateServerName.

Common situations: Copying a nats-server config file to a second machine without changing the server_name/host setting, running two servers with identical names in the same cluster, or snapshot/clone VMs sharing one name.

Related errors

• remote leafnode has same cluster name
• mqtt requires server name to be explicitly set
• account jwt not found
• subject has exceeded number of tokens limit
• attempted to connect to route port

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