{"record":{"id":"bdee006c16139fcc","repo":"docker/cli","slug":"docker-buildkit-environment-variable-expects-boole-bdee00","errorCode":null,"errorMessage":"DOCKER_BUILDKIT environment variable expects boolean value: %w","messagePattern":"DOCKER_BUILDKIT environment variable expects boolean value: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/docker/builder.go","lineNumber":59,"sourceCode":"\t\treturn errors.New(errorMsg)\n\t}\n\tif pluginLoadErr != nil {\n\t\treturn fmt.Errorf(\"%w\\n\\n%s\", pluginLoadErr, errorMsg)\n\t}\n\treturn errors.New(errorMsg)\n}\n\n//nolint:gocyclo\nfunc processBuilder(dockerCli command.Cli, cmd *cobra.Command, args, osargs []string) ([]string, []string, []string, error) {\n\tvar buildKitDisabled, useBuilder, useAlias bool\n\tvar envs []string\n\n\t// check DOCKER_BUILDKIT env var is not empty\n\t// if it is assume we want to use the builder component\n\tif v := os.Getenv(\"DOCKER_BUILDKIT\"); v != \"\" {\n\t\tenabled, err := strconv.ParseBool(v)\n\t\tif err != nil {\n\t\t\treturn args, osargs, nil, fmt.Errorf(\"DOCKER_BUILDKIT environment variable expects boolean value: %w\", err)\n\t\t}\n\t\tif !enabled {\n\t\t\tbuildKitDisabled = true\n\t\t} else {\n\t\t\tuseBuilder = true\n\t\t}\n\t}\n\t// docker bake always requires buildkit; ignore \"DOCKER_BUILDKIT=0\".\n\tif buildKitDisabled && len(args) > 0 && args[0] == \"bake\" {\n\t\tbuildKitDisabled = false\n\t}\n\n\t// if a builder alias is defined, use it instead\n\t// of the default one\n\tbuilderAlias := builderDefaultPlugin\n\taliasMap := dockerCli.ConfigFile().Aliases\n\tif v, ok := aliasMap[keyBuilderAlias]; ok {\n\t\tuseBuilder = true","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker/builder.go#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"Users assuming 'on'/'yes' work (common in other tools); copy-pasting env values from non-Docker docs; CI config templating injecting unexpected values.","solutions":["Set DOCKER_BUILDKIT to a Go-boolean: `export DOCKER_BUILDKIT=1` (enable) or `DOCKER_BUILDKIT=0` (disable).","Unset the variable if you want the default behavior: `unset DOCKER_BUILDKIT`.","Check the shell/rc files, systemd units, and CI matrices for stray DOCKER_BUILDKIT assignments."],"exampleFix":"// before\n$ DOCKER_BUILDKIT=yes docker build .\nError: DOCKER_BUILDKIT environment variable expects boolean value: ...\n\n// after\n$ DOCKER_BUILDKIT=1 docker build .","handlingStrategy":"validation","validationCode":"// Validate DOCKER_BUILDKIT is a Go-boolean before invoking docker build\nimport \"strconv\"\n\nfunc validateBuildkitEnv() error {\n    v := os.Getenv(\"DOCKER_BUILDKIT\")\n    if v == \"\" { return nil }\n    if _, err := strconv.ParseBool(v); err != nil {\n        return fmt.Errorf(\"DOCKER_BUILDKIT=%q is not a boolean (use 1 or 0)\", v)\n    }\n    return nil\n}","typeGuard":"func buildkitEnvValid() bool {\n    v := os.Getenv(\"DOCKER_BUILDKIT\")\n    if v == \"\" { return true }\n    _, err := strconv.ParseBool(v)\n    return err == nil\n}","tryCatchPattern":null,"preventionTips":["Use only 1/0 (or true/false) for DOCKER_BUILDKIT; never 'yes'/'on'.","Lint environment files in CI for DOCKER_BUILDKIT values.","Unset the variable when the default behavior is desired."],"tags":["docker","build","environment","buildkit","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}