{"record":{"id":"7c46d11128d04380","repo":"k3s-io/k3s","slug":"token-is-required","errorCode":null,"errorMessage":"--token is required","messagePattern":"--token is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/cli/agent/agent.go","lineNumber":83,"sourceCode":"\t\tif err := permissions.IsPrivileged(); err != nil {\n\t\t\treturn errors.WithMessage(err, \"agent requires additional privilege if not run with --rootless\")\n\t\t}\n\t}\n\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 {","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/cli/agent/agent.go#L65-L101","documentation":"Agent bootstrap requires either a valid join token or an already-issued client-kubelet certificate pair from a previous join. The check first attempts tls.LoadX509KeyPair on <data-dir>/agent/client-kubelet.crt/key; only if those are missing/invalid AND no --token/--token-file was provided does it fail. So the error means: first run without a token, or a wiped data-dir on rejoin without re-supplying credentials.","triggerScenarios":"First `k3s agent` run with no --token, --token-file, or K3S_TOKEN; data-dir was deleted/corrupted so the cached kubelet client cert is gone and no token is passed; token file path pointing to an empty file that still yields empty Token.","commonSituations":"New node provisioning where the token secret was not distributed; rejoining after rm -rf /var/lib/rancher/k3s without updating the agent unit; token file with wrong permissions read as empty.","solutions":["Get the token from the server (cat /var/lib/rancher/k3s/server/token) and pass it: k3s agent --token <token> --server https://<server>:6443","Or persist it via --token-file / K3S_TOKEN_FILE so restarts don't depend on flags","If this is a rejoin after wiping the data-dir, supply the token again — the old client cert no longer exists"],"exampleFix":"# before\nk3s agent --server https://10.0.0.10:6443  # no token, no cached cert -> --token is required\n\n# after\nK3S_TOKEN=K10...::server:... k3s agent --server https://10.0.0.10:6443","handlingStrategy":"validation","validationCode":"func hasBootstrapCreds(dataDir string, token string) error {\n    cert := filepath.Join(dataDir, \"agent\", \"client-kubelet.crt\")\n    key := filepath.Join(dataDir, \"agent\", \"client-kubelet.key\")\n    if _, err := tls.LoadX509KeyPair(cert, key); err == nil { return nil } // cached creds OK\n    if strings.TrimSpace(token) == \"\" { return errors.New(\"provide --token (from /var/lib/rancher/k3s/server/token) on first join\") }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Automate token distribution from the server into a root-only token file","After wiping a node's data-dir, always re-supply the token","Monitor for empty token-file reads (permissions) in provisioning scripts"],"tags":["agent","token","bootstrap","authentication","cli"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}