k3s-io/k3s · error
Rootless is not supported on windows
Error message
Rootless is not supported on windows
What it means
k3s rootless package (pkg/rootless/rootless_windows.go): the Windows build of k3s ships a stub Rootless() that panics immediately, because rootless mode (user-namespace, slirp/netavark networking) is implemented only for Linux. Seeing this panic means the Windows binary executed code that should only run on Linux builds.
Solutions
- Do not enable rootless mode on Windows: remove the --rootless flag / disable the rootless start path for windows builds
- Guard the call site: only invoke Rootless when runtime.GOOS == 'linux' (or move it behind a linux build tag)
- Run the rootless control plane on a Linux host or VM; Windows nodes should join an existing cluster as agents without rootless
Example fix
// before
if err := rootless.Rootless(stateDir, enableIPv6); err != nil {
return err
}
// after
if runtime.GOOS != "linux" {
return fmt.Errorf("rootless mode is only supported on linux, current GOOS: %s", runtime.GOOS)
}
if err := rootless.Rootless(stateDir, enableIPv6); err != nil {
return err
} Defensive patterns
Strategy: validation
Validate before calling
if runtime.GOOS != "linux" {
return fmt.Errorf("rootless mode requires linux; refusing on %s", runtime.GOOS)
}
return rootless.Rootless(stateDir, enableIPv6) Type guard
func supportsRootless() bool {
return runtime.GOOS == "linux"
} Prevention
- Keep rootless strictly a linux code path: gate flag parsing as well as the call site by GOOS/build tags
- Do not copy linux systemd units (k3s-rootless.service) to windows hosts
- In cross-platform tooling and CI, assert GOOS before exercising pkg/rootless
When it happens
Trigger: Compiling k3s for GOOS=windows and starting it with rootless enabled (the Rootless function invoked during startup); invoking pkg/rootless.Rootless from cross-platform tooling or tests that do not guard on runtime.GOOS.
Common situations: Experimental Windows k3s builds where a start path enables rootless; CI matrix builds running windows binaries against linux-only flags; code changes that call Rootless without a build-tag guard.
Related errors
- Rootless is not supported on windows
- delegated cgroup v2 controllers are required for rootless
- Failed to create image import watcher:
- failed to start etcd client
- failed to start leader controller
AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15).
Data as JSON: /api/errors/1699b996a707b282.
Report an issue: GitHub.
Appendix: source
Thrown at pkg/rootless/rootless_windows.go:4
package rootless
func Rootless(stateDir string, enableIPv6 bool) error {
panic("Rootless is not supported on windows")
}
View on GitHub (pinned to 6ba341e396)