{"record":{"id":"afdccf08c8382b74","repo":"docker/cli","slug":"docker-buildkit-environment-variable-expects-boole","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":"cli/command/cli.go","lineNumber":156,"sourceCode":"\t\tcli.configFile = config.LoadDefaultConfigFile(cli.err)\n\t}\n\treturn cli.configFile\n}\n\n// ServerInfo returns the server version details for the host this client is\n// connected to\nfunc (cli *DockerCli) ServerInfo() ServerInfo {\n\t_ = cli.initialize()\n\treturn cli.serverInfo\n}\n\n// BuildKitEnabled returns buildkit is enabled or not.\nfunc (cli *DockerCli) BuildKitEnabled() (bool, error) {\n\t// use DOCKER_BUILDKIT env var value if set and not empty\n\tif v := os.Getenv(\"DOCKER_BUILDKIT\"); v != \"\" {\n\t\tenabled, err := strconv.ParseBool(v)\n\t\tif err != nil {\n\t\t\treturn false, fmt.Errorf(\"DOCKER_BUILDKIT environment variable expects boolean value: %w\", err)\n\t\t}\n\t\treturn enabled, nil\n\t}\n\t// if a builder alias is defined, we are using BuildKit\n\taliasMap := cli.ConfigFile().Aliases\n\tif _, ok := aliasMap[\"builder\"]; ok {\n\t\treturn true, nil\n\t}\n\n\tsi := cli.ServerInfo()\n\tif si.BuildkitVersion == build.BuilderBuildKit {\n\t\t// The daemon advertised BuildKit as the preferred builder; this may\n\t\t// be either a Linux daemon or a Windows daemon with experimental\n\t\t// BuildKit support enabled.\n\t\treturn true, nil\n\t}\n\n\t// otherwise, assume BuildKit is enabled for Linux, but disabled for","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/cli.go#L138-L174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set DOCKER_BUILDKIT to a canonical boolean token: 1/0, true/false, or TRUE/FALSE.","Unset the variable entirely (export -n DOCKER_BUILDKIT) if you want BuildKit selection to fall through to the builder alias or daemon advertisement logic.","If scripting feature flags, map your own convention to canonical values before exporting: DOCKER_BUILDKIT=$([ \"$BUILDKIT\" = enabled ] && echo 1 || echo 0)."],"exampleFix":"// before\nexport DOCKER_BUILDKIT=yes\ndocker build .\n// after\nexport DOCKER_BUILDKIT=1\ndocker build .","handlingStrategy":"validation","validationCode":"// Validate DOCKER_BUILDKIT before invoking the CLI/build path.\nfunc validateBuildKitEnv() error {\n    if v, ok := os.LookupEnv(\"DOCKER_BUILDKIT\"); ok && v != \"\" {\n        if _, err := strconv.ParseBool(v); err != nil {\n            return fmt.Errorf(\"DOCKER_BUILDKIT must be a boolean (1,0,true,false): got %q\", v)\n        }\n    }\n    return nil\n}","typeGuard":"// isCanonicalBool reports whether v is accepted by strconv.ParseBool.\nfunc isCanonicalBool(v string) bool {\n    _, err := strconv.ParseBool(v)\n    return err == nil\n}","tryCatchPattern":"if _, err := cli.BuildKitEnabled(); err != nil {\n    // log a hint to set DOCKER_BUILDKIT to 1/0/true/false and fall back to legacy builder\n}","preventionTips":["Centralize feature-flag-to-boolean mapping in your shell profile so only canonical tokens reach DOCKER_BUILDKIT.","Add a CI lint step that rejects non-canonical DOCKER_BUILDKIT values."],"tags":["environment-variable","buildkit","build","configuration"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}