k3s-io/k3s · error

--server is required

Error message

--server is required

What it means

Straightforward startup validation on the agent: the supervisor URL (--server / K3S_URL / config.yaml server) is mandatory because an agent has no local control plane to talk to otherwise. An empty ServerURL aborts before any network or token handling.

Solutions

1. Pass the server URL: k3s agent --server https://<server-host>:6443 --token <token>
2. Or set server: https://<server>:6443 in /etc/rancher/k3s/config.yaml (or K3S_URL) and restart the agent
3. Verify the rendered unit/config actually contains the value: systemctl cat k3s-agent

Example fix

# before
k3s agent --token K10...  # -> --server is required

# after
k3s agent --server https://10.0.0.10:6443 --token K10...

if cfg.ServerURL == "" {
    return errors.New("agent requires --server / K3S_URL / config.yaml server (e.g. https://host:6443)")
}

func hasServerURL(s string) bool { return strings.TrimSpace(s) != "" }

When it happens

Trigger: Running `k3s agent` with neither --server nor K3S_URL nor a server: entry in /etc/rancher/k3s/config.yaml; a config template that failed to substitute the server value.

Common situations: Copy-pasted systemd unit missing the environment/flag; automation where the server variable was unset so the flag rendered empty; misordered migration from server to agent role on a node.

Related errors

• etcd-snapshot-reconcile-interval must be greater than 0s
• invalid node-external-ip
• Cannot configure unknown flannel backend
• cluster-cidr: and service-cidr: , must share the same IP…
• failed to parse config location

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

Appendix: source

Thrown at pkg/cli/agent/agent.go:87

	if cmds.AgentConfig.TokenFile != "" {
		token, err := util.ReadFile(ctx, cmds.AgentConfig.TokenFile)
		if err != nil {
			return err
		}
		cmds.AgentConfig.Token = token
	}

	clientKubeletCert := filepath.Join(cmds.AgentConfig.DataDir, "agent", "client-kubelet.crt")
	clientKubeletKey := filepath.Join(cmds.AgentConfig.DataDir, "agent", "client-kubelet.key")
	_, err := tls.LoadX509KeyPair(clientKubeletCert, clientKubeletKey)

	if err != nil && cmds.AgentConfig.Token == "" {
		return errors.New("--token is required")
	}

	if cmds.AgentConfig.ServerURL == "" {
		return errors.New("--server is required")
	}

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

	logrus.Info("Starting " + version.Program + " agent " + clx.App.Version)

	dataDir, err := datadir.LocalHome(cmds.AgentConfig.DataDir, cmds.AgentConfig.Rootless)
	if err != nil {
		return err
	}

	cfg := cmds.AgentConfig

View on GitHub (pinned to 6ba341e396)