docker/cli · error

DOCKER_BUILDKIT environment variable expects boolean value

Error message

DOCKER_BUILDKIT environment variable expects boolean value: %w

What it means

Returned by processBuilder() when the DOCKER_BUILDKIT environment variable is set to a non-empty value that strconv.ParseBool cannot interpret as a boolean. %w wraps the strconv error. ParseBool accepts 1,t,T,TRUE,true,True,0,f,F,FALSE,false,False — anything else (e.g. 'yes','on','enable', empty-handled-elsewhere) fails.

Solutions

1. Set DOCKER_BUILDKIT to a Go-boolean: `export DOCKER_BUILDKIT=1` (enable) or `DOCKER_BUILDKIT=0` (disable).
2. Unset the variable if you want the default behavior: `unset DOCKER_BUILDKIT`.
3. Check the shell/rc files, systemd units, and CI matrices for stray DOCKER_BUILDKIT assignments.

Example fix

// before
$ DOCKER_BUILDKIT=yes docker build .
Error: DOCKER_BUILDKIT environment variable expects boolean value: ...

// after
$ DOCKER_BUILDKIT=1 docker build .

// Validate DOCKER_BUILDKIT is a Go-boolean before invoking docker build
import "strconv"

func validateBuildkitEnv() error {
    v := os.Getenv("DOCKER_BUILDKIT")
    if v == "" { return nil }
    if _, err := strconv.ParseBool(v); err != nil {
        return fmt.Errorf("DOCKER_BUILDKIT=%q is not a boolean (use 1 or 0)", v)
    }
    return nil
}

func buildkitEnvValid() bool {
    v := os.Getenv("DOCKER_BUILDKIT")
    if v == "" { return true }
    _, err := strconv.ParseBool(v)
    return err == nil
}

When it happens

Trigger: Setting `DOCKER_BUILDKIT=yes`, `DOCKER_BUILDKIT=on`, `DOCKER_BUILDKIT=enable`, or `DOCKER_BUILDKIT= ` (quoted space) in the shell or a systemd/compose unit, then running any builder-forwarded docker command.

Common situations: Users assuming 'on'/'yes' work (common in other tools); copy-pasting env values from non-Docker docs; CI config templating injecting unexpected values.

Related errors

• invalid image reference for service
• unexpected environment variable
• %w %s
• other flags may not be combined with --rollback
• duplicate mount target

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

Appendix: source

Thrown at cmd/docker/builder.go:59

		return errors.New(errorMsg)
	}
	if pluginLoadErr != nil {
		return fmt.Errorf("%w\n\n%s", pluginLoadErr, errorMsg)
	}
	return errors.New(errorMsg)
}

//nolint:gocyclo
func processBuilder(dockerCli command.Cli, cmd *cobra.Command, args, osargs []string) ([]string, []string, []string, error) {
	var buildKitDisabled, useBuilder, useAlias bool
	var envs []string

	// check DOCKER_BUILDKIT env var is not empty
	// if it is assume we want to use the builder component
	if v := os.Getenv("DOCKER_BUILDKIT"); v != "" {
		enabled, err := strconv.ParseBool(v)
		if err != nil {
			return args, osargs, nil, fmt.Errorf("DOCKER_BUILDKIT environment variable expects boolean value: %w", err)
		}
		if !enabled {
			buildKitDisabled = true
		} else {
			useBuilder = true
		}
	}
	// docker bake always requires buildkit; ignore "DOCKER_BUILDKIT=0".
	if buildKitDisabled && len(args) > 0 && args[0] == "bake" {
		buildKitDisabled = false
	}

	// if a builder alias is defined, use it instead
	// of the default one
	builderAlias := builderDefaultPlugin
	aliasMap := dockerCli.ConfigFile().Aliases
	if v, ok := aliasMap[keyBuilderAlias]; ok {
		useBuilder = true

View on GitHub (pinned to 4f84911bfe)