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.

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)

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: %w
• Initial server URL host is not defined for load balancer
• --token is required
• service %s is not recognized

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