k3s-io/k3s · error

cri-dockerd disabled at build time

Error message

cri-dockerd disabled at build time

What it means

Returned by cridockerd.Run() in builds compiled with the no_cri_dockerd build tag. That tag replaces the cri-dockerd shim with a stub so k3s binaries can ship without the Docker CRI bridge; any attempt to exercise the cri-dockerd code path (e.g. --docker) immediately returns this error. It is a build-capability error, not a runtime failure of Docker itself.

Source

Thrown at pkg/agent/cridockerd/nocridockerd.go:13

//go:build no_cri_dockerd

package cridockerd

import (
	"context"
	"errors"

	"github.com/k3s-io/k3s/pkg/daemons/config"
)

func Run(ctx context.Context, cfg *config.Node) error {
	return errors.New("cri-dockerd disabled at build time")
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Use the official k3s release binary, which includes cri-dockerd, if you need --docker
2. Rebuild from source without the no_cri_dockerd build tag
3. Switch the node to the default embedded containerd (remove --docker) if the Docker runtime is not strictly required

Example fix

# before (binary built with -tags no_cri_dockerd)
k3s agent --docker  # -> cri-dockerd disabled at build time

# after
curl -sfL https://get.k3s.io | sh -  # official binary includes cri-dockerd
k3s agent --docker

// Before allowing --docker, verify the build ships cri-dockerd:
if cfg.Docker {
    if err := cridockerd.Run(ctx, nil); err != nil && err.Error() == "cri-dockerd disabled at build time" {
        return errors.New("this k3s build does not include cri-dockerd; use embedded containerd or the official binary")
    }
}

if err := cridockerd.Run(ctx, cfg); err != nil {
    if err.Error() == "cri-dockerd disabled at build time" {
        // surface actionable message: binary stripped of cri-dockerd; refuse --docker
    }
}

When it happens

Trigger: Running a k3s build produced with -tags no_cri_dockerd (as done by some distros/minimal builds) while passing --docker or otherwise invoking the cri-dockerd daemon path.

Common situations: Distro-packaged or custom-built k3s binaries stripped of cri-dockerd; users following default k3s docs (which allow --docker) against a stripped binary; CI images built with the no_cri_dockerd tag.

Related errors

• embedded registry mirror requires embedded containerd
• default runtime %s was not found

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/1a3a5e604701106d. Report an issue: GitHub.