{"record":{"id":"1a453a300d1531b4","repo":"k3s-io/k3s","slug":"failed-to-create-path-for-symlink-v","errorCode":null,"errorMessage":"failed to create path for symlink: %v","messagePattern":"failed to create path for symlink: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/server/server.go","lineNumber":530,"sourceCode":"\tenvList := []string{}\n\tenvList = append(envList, strings.FieldsFunc(os.Getenv(\"NO_PROXY\"), splitter)...)\n\tenvList = append(envList, strings.FieldsFunc(os.Getenv(\"no_proxy\"), splitter)...)\n\tenvList = append(envList,\n\t\t\".svc\",\n\t\t\".\"+config.ClusterDomain,\n\t\tutil.JoinIPNets(config.ClusterIPRanges),\n\t\tutil.JoinIPNets(config.ServiceIPRanges),\n\t)\n\tos.Unsetenv(\"no_proxy\")\n\treturn os.Setenv(\"NO_PROXY\", strings.Join(envList, \",\"))\n}\n\nfunc writeConfigSymlink(kubeconfig, kubeconfigSymlink string) error {\n\tif err := os.Remove(kubeconfigSymlink); err != nil && !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"failed to remove %s file: %v\", kubeconfigSymlink, err)\n\t}\n\tif err := os.MkdirAll(filepath.Dir(kubeconfigSymlink), 0755); err != nil {\n\t\treturn fmt.Errorf(\"failed to create path for symlink: %v\", err)\n\t}\n\tif err := os.Symlink(kubeconfig, kubeconfigSymlink); err != nil {\n\t\treturn fmt.Errorf(\"failed to create symlink: %v\", err)\n\t}\n\treturn nil\n}\n\nfunc isSymlink(config string) bool {\n\tif fi, err := os.Lstat(config); err == nil && (fi.Mode()&os.ModeSymlink == os.ModeSymlink) {\n\t\treturn true\n\t}\n\treturn false\n}\n\nfunc setNodeLabelsAndAnnotations(ctx context.Context, nodes v1.NodeClient, config *Config) error {\n\tif config.DisableAgent || config.ControlConfig.DisableAPIServer {\n\t\treturn nil\n\t}","sourceCodeStart":512,"sourceCodeEnd":548,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/server/server.go#L512-L548","documentation":"Before creating the kubeconfig symlink, k3s ensures its parent directory exists with os.MkdirAll (typically /etc/rancher/k3s). Failure of that mkdir - permission denied, path component is a file, read-only or immutable filesystem - is returned as this error during server startup.","triggerScenarios":"Server start where MkdirAll(/etc/rancher/k3s) fails: running k3s as a non-root user without write access to /etc, /etc/rancher existing as a regular file, a read-only root filesystem (immutable appliances, containers without writable /etc), or SELinux denial.","commonSituations":"Running the k3s binary manually as an unprivileged user instead of via the systemd unit; containerized deployments missing a writable /etc mount; a file accidentally created at /etc/rancher; disk or filesystem errors (I/O errors surface here too).","solutions":["Check the path shape: ls -ld /etc/rancher /etc/rancher/k3s - remove any regular file occupying a needed directory component.","Run k3s as root (or the systemd unit) so it can create /etc/rancher/k3s, or pre-create the directory owned by the runtime user.","In containers, ensure /etc/rancher is a writable volume/mount.","Address any filesystem-level cause (read-only mount, SELinux denial) shown by the wrapped %v error."],"exampleFix":"# before: /etc/rancher is a file\nls -ld /etc/rancher  # '-rw-r--r-- a file'\n\n# after\nsudo rm /etc/rancher && sudo mkdir -p /etc/rancher/k3s && sudo systemctl restart k3s","handlingStrategy":"validation","validationCode":"// Ensure the symlink parent dir is a writable directory before start\nif fi, err := os.Stat(dir); err == nil && !fi.IsDir() {\n    log.Fatalf(\"%s exists but is not a directory\", dir)\n} else if err := os.MkdirAll(dir, 0755); err != nil {\n    log.Fatalf(\"cannot create %s: %v\", dir, err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-create /etc/rancher/k3s with correct ownership in provisioning","Run k3s via its systemd unit (root) or grant the runtime user write access","Mount /etc/rancher as a writable volume in containers"],"tags":["filesystem","permissions","startup","kubeconfig"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}