docker/cli · error

DOCKER_BUILDKIT environment variable expects boolean value

Error message

DOCKER_BUILDKIT environment variable expects boolean value: %w

What it means

This error is returned by DockerCli.BuildKitEnabled() when the DOCKER_BUILDKIT environment variable is set to a value that strconv.ParseBool cannot interpret. ParseBool only accepts the canonical set {1,t,T,TRUE,true,True,0,f,F,FALSE,false,False}; any other string (e.g. "yes", "on", "enable") is rejected. The error is wrapped from the underlying strconv.ParseBool failure and surfaces during any build or buildx command that checks BuildKit status.

Solutions

1. Set DOCKER_BUILDKIT to a canonical boolean token: 1/0, true/false, or TRUE/FALSE.
2. Unset the variable entirely (export -n DOCKER_BUILDKIT) if you want BuildKit selection to fall through to the builder alias or daemon advertisement logic.
3. If scripting feature flags, map your own convention to canonical values before exporting: DOCKER_BUILDKIT=$([ "$BUILDKIT" = enabled ] && echo 1 || echo 0).

Example fix

// before
export DOCKER_BUILDKIT=yes
docker build .
// after
export DOCKER_BUILDKIT=1
docker build .

// Validate DOCKER_BUILDKIT before invoking the CLI/build path.
func validateBuildKitEnv() error {
    if v, ok := os.LookupEnv("DOCKER_BUILDKIT"); ok && v != "" {
        if _, err := strconv.ParseBool(v); err != nil {
            return fmt.Errorf("DOCKER_BUILDKIT must be a boolean (1,0,true,false): got %q", v)
        }
    }
    return nil
}

// isCanonicalBool reports whether v is accepted by strconv.ParseBool.
func isCanonicalBool(v string) bool {
    _, err := strconv.ParseBool(v)
    return err == nil
}

if _, err := cli.BuildKitEnabled(); err != nil {
    // log a hint to set DOCKER_BUILDKIT to 1/0/true/false and fall back to legacy builder
}

When it happens

Trigger: Calling any build-related command (docker build, docker buildx ...) while DOCKER_BUILDKIT is exported with a non-canonical boolean token. The check at cli.go:153-158 reads os.Getenv("DOCKER_BUILDKIT") and immediately calls strconv.ParseBool(v) when the value is non-empty; the error path is taken for values like "yes", "2", "on", "", etc.

Common situations: Users exporting DOCKER_BUILDKIT=yes (common copy-paste from blog posts), DOCKER_BUILDKIT=on, DOCKER_BUILDKIT=enable, or a shell variable that accidentally expanded to a non-boolean. Also occurs in CI where a generic feature-flag convention (e.g. "on"/"off") is reused for the Docker-specific variable.

Related errors

• failed to parse custom headers from
• failed to set custom headers from
• failed to set custom headers from
• failed to read credentials from DOCKER_AUTH_CONFIG
• %w %s

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/afdccf08c8382b74. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/cli.go:156

		cli.configFile = config.LoadDefaultConfigFile(cli.err)
	}
	return cli.configFile
}

// ServerInfo returns the server version details for the host this client is
// connected to
func (cli *DockerCli) ServerInfo() ServerInfo {
	_ = cli.initialize()
	return cli.serverInfo
}

// BuildKitEnabled returns buildkit is enabled or not.
func (cli *DockerCli) BuildKitEnabled() (bool, error) {
	// use DOCKER_BUILDKIT env var value if set and not empty
	if v := os.Getenv("DOCKER_BUILDKIT"); v != "" {
		enabled, err := strconv.ParseBool(v)
		if err != nil {
			return false, fmt.Errorf("DOCKER_BUILDKIT environment variable expects boolean value: %w", err)
		}
		return enabled, nil
	}
	// if a builder alias is defined, we are using BuildKit
	aliasMap := cli.ConfigFile().Aliases
	if _, ok := aliasMap["builder"]; ok {
		return true, nil
	}

	si := cli.ServerInfo()
	if si.BuildkitVersion == build.BuilderBuildKit {
		// The daemon advertised BuildKit as the preferred builder; this may
		// be either a Linux daemon or a Windows daemon with experimental
		// BuildKit support enabled.
		return true, nil
	}

	// otherwise, assume BuildKit is enabled for Linux, but disabled for

View on GitHub (pinned to 4f84911bfe)