invalid flag use; --server is required with --disable-etcd

Error message

invalid flag use; --server is required with --disable-etcd

What it means

--disable-etcd runs a server as a control-plane member without a local datastore, so it must obtain all cluster state from an existing server via --server (JoinURL). With no JoinURL the node would have neither local etcd nor a peer to sync from, which k3s refuses at startup.

Source

Thrown at pkg/cli/server/server.go:258

		}
	} else {
		logrus.Info("ETCD snapshots are disabled")
	}

	if cfg.ClusterResetRestorePath != "" && !cfg.ClusterReset {
		return errors.New("invalid flag use; --cluster-reset required with --cluster-reset-restore-path")
	}

	serverConfig.ControlConfig.ClusterReset = cfg.ClusterReset
	serverConfig.ControlConfig.ClusterResetRestorePath = cfg.ClusterResetRestorePath
	serverConfig.ControlConfig.SystemDefaultRegistry = cfg.SystemDefaultRegistry

	if serverConfig.ControlConfig.SupervisorPort == 0 {
		serverConfig.ControlConfig.SupervisorPort = serverConfig.ControlConfig.HTTPSPort
	}

	if serverConfig.ControlConfig.DisableETCD && serverConfig.ControlConfig.JoinURL == "" {
		return errors.New("invalid flag use; --server is required with --disable-etcd")
	}

	if serverConfig.ControlConfig.Datastore.Endpoint != "" && serverConfig.ControlConfig.DisableAPIServer {
		return errors.New("invalid flag use; cannot use --disable-apiserver with --datastore-endpoint")
	}

	if serverConfig.ControlConfig.Datastore.Endpoint != "" && serverConfig.ControlConfig.DisableETCD {
		return errors.New("invalid flag use; cannot use --disable-etcd with --datastore-endpoint")
	}

	if serverConfig.ControlConfig.DisableAPIServer {
		// Servers without a local apiserver need to connect to the apiserver via the proxy load-balancer.
		serverConfig.ControlConfig.APIServerPort = cmds.AgentConfig.LBServerPort
		// If the supervisor and externally-facing apiserver are not on the same port, the proxy will
		// have a separate load-balancer for the apiserver that we need to use instead.
		if serverConfig.ControlConfig.SupervisorPort != serverConfig.ControlConfig.HTTPSPort {
			serverConfig.ControlConfig.APIServerPort = cmds.AgentConfig.LBServerPort - 1
		}

View on GitHub (pinned to 6ba341e396)

Solutions

Add `--server https://<existing-server>:6443` (or `server:` in config.yaml) so the node joins an existing cluster
If this node should hold datastore itself, remove --disable-etcd and let it run embedded etcd
Verify the flag reached the process: `systemctl cat k3s` and `tr \0 ' ' /proc/$(pidof k3s)/cmdline`

Example fix

# before
k3s server --disable-etcd

# after
k3s server --disable-etcd --server https://10.0.0.10:6443 --token <cluster-token>

Defensive patterns

Strategy: validation

Validate before calling

# preflight for disable-etcd nodes
if grep -qE '^(--)?disable-etcd|disable-etcd: true' /etc/rancher/k3s/config.yaml 2>/dev/null || printf '%s' "$@" | grep -q -- '--disable-etcd'; then
  grep -qE '^server: ' /etc/rancher/k3s/config.yaml || [ -n "$K3S_URL" ] || { echo '--server is required with --disable-etcd'; exit 1; }
fi

Prevention

Templated node provisioning should assert: disable-etcd implies server URL
Document per-role flag matrices for embedded-etcd HA clusters
Smoke-test new control-plane node configs with `k3s server --help`-driven lint before first boot

When it happens

Trigger: `k3s server --disable-etcd` with no --server flag and no `server:` entry in /etc/rancher/k3s/config.yaml (the server-role config, not the agent one).

Common situations: Adding control-plane nodes to an embedded-etcd HA cluster and forgetting --server on the new node; server URL present only in the agent config section so it is not picked up; env var K3S_URL unset in the unit file.

Related errors

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