{"record":{"id":"e03804a17486020a","repo":"nats-io/nats-server","slug":"duplicate-server-name","errorCode":null,"errorMessage":"duplicate server name","messagePattern":"duplicate server name","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":217,"sourceCode":"\n\t// ErrClusterNameReserved signals that the cluster name is reserved for internal protocol use.\n\tErrClusterNameReserved = errors.New(\"cluster name is reserved\")\n\n\t// ErrMalformedSubject is returned when a subscription is made with a subject that does not conform to subject rules.\n\tErrMalformedSubject = errors.New(\"malformed subject\")\n\n\t// ErrSubscribePermissionViolation is returned when processing of a subscription fails due to permissions.\n\tErrSubscribePermissionViolation = errors.New(\"subscribe permission violation\")\n\n\t// ErrNoTransforms signals no subject transforms are available to map this subject.\n\tErrNoTransforms = errors.New(\"no matching transforms available\")\n\n\t// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it\n\tErrCertNotPinned = errors.New(\"certificate not pinned\")\n\n\t// ErrDuplicateServerName is returned when processing a server remote connection and\n\t// the server reports that this server name is already used in the cluster.\n\tErrDuplicateServerName = errors.New(\"duplicate server name\")\n\n\t// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.\n\tErrMinimumVersionRequired = errors.New(\"minimum version required\")\n\t// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used\n\t// when rejecting a remote due to leafnodes.min_version.\n\tErrLeafNodeMinVersionRejected = errors.New(\"connection rejected since minimum version required is\")\n\n\t// ErrInvalidMappingDestination is used for all subject mapping destination errors\n\tErrInvalidMappingDestination = errors.New(\"invalid mapping destination\")\n\n\t// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping\n\tErrInvalidMappingDestinationSubject = fmt.Errorf(\"%w: invalid transform\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards\n\tErrMappingDestinationNotUsingAllWildcards = fmt.Errorf(\"%w: not using all of the token wildcard(s)\", ErrInvalidMappingDestination)\n\n\t// ErrUnknownMappingDestinationFunction is returned when a subject mapping destination contains an unknown mustache-escaped mapping function.\n\tErrUnknownMappingDestinationFunction = fmt.Errorf(\"%w: unknown function\", ErrInvalidMappingDestination)","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L199-L235","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set a unique server name for each server in the cluster (e.g. server_name: \"nats-1\") and restart the offending server.","If no server_name is set, derive a unique name from hostname/IP instead of reusing a static value.","Check for stale/ghost connections or lingering processes of the same server and shut them down."],"exampleFix":"// before\necho 'server_name: \"nats\"' > /etc/nats/nats-a.cfg\ncp /etc/nats/nats-a.cfg /etc/nats/nats-b.cfg\n// after\ncat > /etc/nats/nats-b.cfg <<'EOF'\nserver_name: \"nats-b\"\nEOF","handlingStrategy":"validation","validationCode":"if serverName == \"\" || duplicateInCluster(serverName) {\n    return errors.New(\"choose a unique server_name before joining the cluster\")\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, server.ErrDuplicateServerName) {\n    log.Fatalf(\"server name already in use: pick a unique server_name\")\n}","preventionTips":["Make server_name mandatory and unique per node in your config templating.","Never clone configs between machines without changing server_name.","Include hostname/zone in generated server names."],"tags":["nats","cluster","server-name","configuration"],"backgroundTag":"duplicate-server-name","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}