{"record":{"id":"ea4c468eb1fe3fbc","repo":"k3s-io/k3s","slug":"server-is-required","errorCode":null,"errorMessage":"--server is required","messagePattern":"--server is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/agent/agent.go","lineNumber":87,"sourceCode":"\n\tif cmds.AgentConfig.TokenFile != \"\" {\n\t\ttoken, err := util.ReadFile(ctx, cmds.AgentConfig.TokenFile)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tcmds.AgentConfig.Token = token\n\t}\n\n\tclientKubeletCert := filepath.Join(cmds.AgentConfig.DataDir, \"agent\", \"client-kubelet.crt\")\n\tclientKubeletKey := filepath.Join(cmds.AgentConfig.DataDir, \"agent\", \"client-kubelet.key\")\n\t_, err := tls.LoadX509KeyPair(clientKubeletCert, clientKubeletKey)\n\n\tif err != nil && cmds.AgentConfig.Token == \"\" {\n\t\treturn errors.New(\"--token is required\")\n\t}\n\n\tif cmds.AgentConfig.ServerURL == \"\" {\n\t\treturn errors.New(\"--server is required\")\n\t}\n\n\tif cmds.AgentConfig.FlannelIface != \"\" && len(cmds.AgentConfig.NodeIP.Value()) == 0 {\n\t\tip, err := util.GetIPFromInterface(cmds.AgentConfig.FlannelIface)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tcmds.AgentConfig.NodeIP.Set(ip)\n\t}\n\n\tlogrus.Info(\"Starting \" + version.Program + \" agent \" + clx.App.Version)\n\n\tdataDir, err := datadir.LocalHome(cmds.AgentConfig.DataDir, cmds.AgentConfig.Rootless)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tcfg := cmds.AgentConfig","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/agent/agent.go#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the server URL: k3s agent --server https://<server-host>:6443 --token <token>","Or set server: https://<server>:6443 in /etc/rancher/k3s/config.yaml (or K3S_URL) and restart the agent","Verify the rendered unit/config actually contains the value: systemctl cat k3s-agent"],"exampleFix":"# before\nk3s agent --token K10...  # -> --server is required\n\n# after\nk3s agent --server https://10.0.0.10:6443 --token K10...","handlingStrategy":"validation","validationCode":"if cfg.ServerURL == \"\" {\n    return errors.New(\"agent requires --server / K3S_URL / config.yaml server (e.g. https://host:6443)\")\n}","typeGuard":"func hasServerURL(s string) bool { return strings.TrimSpace(s) != \"\" }","tryCatchPattern":null,"preventionTips":["Template agent systemd units with required_env checks before ExecStart","Fail fast in scripts: test -n \"$K3S_URL\"","Keep server + token in the same config source so one is never missing"],"tags":["agent","cli","server","config","validation"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}