k3s-io/k3s · critical

server node name not set

Error message

server node name not set

What it means

setName persists an etcd member name '<ServerNodeName>-<uuid8>' in a file; when the file is missing or force=true (fresh cluster / cluster-reset), it needs ServerNodeName to build that name. Empty ServerNodeName (normally defaulted from the hostname) makes member naming impossible.

Source

Thrown at pkg/etcd/etcd.go:714

	}

	return e.handler(handler), nil
}

// setName sets a unique name for this cluster member. The first time this is called,
// or if force is set to true, a new name will be generated and written to disk. The persistent
// name is used on subsequent calls.
func (e *ETCD) setName(force bool) error {
	// don't create the name file if etcd is disabled
	if e.config.DisableETCD {
		return nil
	}

	fileName := nameFile(e.config)
	data, err := os.ReadFile(fileName)
	if os.IsNotExist(err) || force {
		if e.config.ServerNodeName == "" {
			return errors.New("server node name not set")
		}
		e.name = e.config.ServerNodeName + "-" + uuid.New().String()[:8]
		if err := os.MkdirAll(filepath.Dir(fileName), 0700); err != nil {
			return err
		}
		return os.WriteFile(fileName, []byte(e.name), 0600)
	} else if err != nil {
		return err
	}
	e.name = string(data)
	return nil
}

// handler wraps the handler with routes for database info
func (e *ETCD) handler(next http.Handler) http.Handler {
	r := mux.NewRouter()
	r.NotFoundHandler = next

View on GitHub (pinned to 6ba341e396)

Solutions

1. Set a hostname on the host/container (hostnamectl or --hostname on docker run).
2. Or pass the name explicitly: k3s server --node-name <unique-name> (K3S_NODE_NAME).
3. Restart k3s; setName will write the name file and continue.

Example fix

# before: empty hostname
$ hostname
(empty)
# after
hostnamectl set-hostname node-a   # or: k3s server --node-name node-a

// Pre-flight the node name before k3s start:
func nodeNameSet(cfg Config) error {
	if cfg.ServerNodeName == "" {
		hn, err := os.Hostname()
		if err != nil || hn == "" {
			return errors.New("no node name: set hostname or pass --node-name")
		}
	}
	return nil
}

if err := e.setName(true); err != nil {
	if strings.Contains(err.Error(), "server node name not set") {
		// provision hostname or --node-name, then retry start
	}
}

When it happens

Trigger: os.Hostname() returning an empty string (broken container/VM hostname); config explicitly setting an empty node-name; running with a stripped environment where hostname resolution fails.

Common situations: Containers started with --hostname '' or a misconfigured runtime; minimal chroots; automated environments where hostname was unset.

Related errors

• duplicate node name found, please use a unique name for this
• Managed etcd cluster membership was previously reset, please
• no bootstrap data found in datastore - check server token va
• no bootstrap data is available to reconcile against
• etcd datastore disabled

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/8d611a356bd4736b. Report an issue: GitHub.