kubernetes/kubernetes · error

chroot is not implemented on Windows

Error message

chroot is not implemented on Windows

What it means

Returned by Chroot() in the Windows-only build (chroot_windows.go, //go:build windows). The POSIX chroot(2) syscall does not exist on Windows, so kubeadm's Chroot helper is a stub that always errors. Code calling util.Chroot on Windows cannot perform a chroot.

Source

Thrown at cmd/kubeadm/app/util/chroot_windows.go:29

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package util

import (
	"k8s.io/kubernetes/cmd/kubeadm/app/util/errors"
)

// Chroot chroot()s to the new path.
// NB: All file paths after this call are effectively relative to
// `rootfs`
func Chroot(rootfs string) error {
	return errors.New("chroot is not implemented on Windows")
}

View on GitHub (pinned to b882c60b40)

Solutions

1. Avoid the chroot code path on Windows; gate callers with a runtime.GOOS check.
2. Run the workflow on Linux where Chroot is implemented (chroot.go, the !windows build).
3. Refactor the caller to not require chroot semantics on Windows.

Example fix

// before
if err := util.Chroot(rootfs); err != nil { return err }

// after
if runtime.GOOS != "windows" {
    if err := util.Chroot(rootfs); err != nil { return err }
}

if runtime.GOOS == "windows" {
    return errors.New("util.Chroot is not supported on Windows; restructure to avoid chroot")
}

func chrootSupported() bool { return runtime.GOOS != "windows" }

When it happens

Trigger: Any code path on a Windows build that invokes util.Chroot(rootfs). The function unconditionally returns this error.

Common situations: Running/porting kubeadm or a kubeadm-derived tool on Windows where a shared code path calls Chroot. kubeadm control-plane nodes are Linux-only, so this mainly affects experimentation/ports.

Related errors

• --cleanup-and-exit is not implemented on Windows
• the kubeadm process must be run by a user with elevated priv
• kubelet needs to run with elevated permissions!
• failed os init: %w
• shell not specified

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/1cf6156a11a57fe2. Report an issue: GitHub.