k3s-io/k3s · error
Rootless is not supported on windows
Error message
Rootless is not supported on windows
What it means
k3s rootlessports package (pkg/rootlessports/controller_windows.go): on Windows builds Register() is a stub that panics, because the rootless port-forwarding controller (service LB via rootlesskit) only exists for Linux. The panic indicates the agent's controller-registration path executed the Windows stub.
Source
Thrown at pkg/rootlessports/controller_windows.go:10
package rootlessports
import (
"context"
corev1 "github.com/rancher/wrangler/v3/pkg/generated/controllers/core/v1"
)
func Register(ctx context.Context, serviceController corev1.ServiceController, enabled bool, httpsPort int) error {
panic("Rootless is not supported on windows")
}
View on GitHub (pinned to 6ba341e396)
Solutions
- Disable rootless port forwarding on Windows nodes: drop the rootless/rootless-ports related flags from the windows k3s invocation
- Guard the registration call: skip rootlessports.Register when runtime.GOOS != 'linux'
- Use a Linux node (or WSL2 VM) when rootless service load balancing is required
Example fix
// before
if err := rootlessports.Register(ctx, serviceController, enabled, httpsPort); err != nil {
return err
}
// after
if runtime.GOOS == "linux" {
if err := rootlessports.Register(ctx, serviceController, enabled, httpsPort); err != nil {
return err
}
} Defensive patterns
Strategy: validation
Validate before calling
if runtime.GOOS == "linux" {
if err := rootlessports.Register(ctx, serviceController, enabled, httpsPort); err != nil {
return err
}
} Type guard
func supportsRootlessPorts() bool {
return runtime.GOOS == "linux"
} Prevention
- Register rootless ports only on linux nodes; windows agents must skip this controller
- Keep windows k3s configuration free of rootless/service-LB rootless settings copied from linux configs
- Add GOOS assertions in unit tests that call rootlessports.Register so windows CI fails loudly at test time, not at runtime
When it happens
Trigger: Windows k3s build reaching agent controller registration with rootless ports enabled (rootless mode or the service load balancer path that calls rootlessports.Register); calling Register unconditionally from cross-platform code.
Common situations: Running experimental windows binaries with rootless/service-LB settings carried over from linux configs; refactors that register rootless ports without a GOOS guard; CI running windows binaries through linux-oriented startup steps.
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 wrangler controllers
AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15).
Data as JSON: /api/errors/e1b1590fab05922a.
Report an issue: GitHub.