invalid flag use; cannot use --disable-apiserver with --data

Error message

invalid flag use; cannot use --disable-apiserver with --datastore-endpoint

What it means

--disable-apiserver designates a server that skips the local apiserver (e.g. an etcd-only member) and reaches the API through another server's load-balancer. --datastore-endpoint configures an external datastore for the embedded apiserver, so the two flags describe incompatible topologies and k3s rejects the combination.

Source

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

	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
		}
	}

	if cmds.AgentConfig.FlannelIface != "" && len(cmds.AgentConfig.NodeIP.Value()) == 0 {
		ip, err := util.GetIPFromInterface(cmds.AgentConfig.FlannelIface)

View on GitHub (pinned to 6ba341e396)

Solutions

If using an external datastore, remove --disable-apiserver and let this node run an apiserver against the datastore
If running etcd-only members with --disable-apiserver, remove --datastore-endpoint and join with --server instead
Audit config.yaml, env files and systemd drop-ins for the leftover flag before restart

Example fix

# before
k3s server --disable-apiserver --datastore-endpoint=mysql://u:p@db:3306/k3s

# after
k3s server --datastore-endpoint=mysql://u:p@db:3306/k3s

Defensive patterns

Strategy: validation

Validate before calling

# reject mutually exclusive topology flags
if printf '%s' "$K3S_DATASTORE_ENDPOINT" | grep -q . && printf '%s' "$@" | grep -q -- '--disable-apiserver'; then
  echo 'cannot use --disable-apiserver with --datastore-endpoint'; exit 1
fi

Prevention

Encode cluster topology as a single variable (embedded vs external datastore) and derive flags from it
Clean env vars (K3S_DATASTORE_*) when switching topologies
Config-management (Ansible/Helm) should validate flag combinations per role before rollout

When it happens

Trigger: `k3s server --disable-apiserver --datastore-endpoint=mysql://user:pass@host:3306/k3s` (any external datastore URI: MySQL, Postgres, etcd).

Common situations: Migrating a cluster from embedded etcd to an external datastore and leaving stale HA flags behind; environment K3S_DATASTORE_ENDPOINT set on a node configured for split control-plane roles.

Related errors

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