{"record":{"id":"d641860bf4ed4999","repo":"wagoodman/dive","slug":"cannot-find-docker-client-executable","errorCode":null,"errorMessage":"cannot find docker client executable","messagePattern":"cannot find docker client executable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dive/image/docker/cli.go","lineNumber":16,"sourceCode":"package docker\n\nimport (\n\t\"fmt\"\n\t\"github.com/wagoodman/dive/internal/log\"\n\t\"github.com/wagoodman/dive/internal/utils\"\n\t\"os\"\n\t\"os/exec\"\n\t\"strings\"\n)\n\n// runDockerCmd runs a given Docker command in the current tty\nfunc runDockerCmd(cmdStr string, args ...string) error {\n\n\tif !isDockerClientBinaryAvailable() {\n\t\treturn fmt.Errorf(\"cannot find docker client executable\")\n\t}\n\n\tallArgs := utils.CleanArgs(append([]string{cmdStr}, args...))\n\n\tfullCmd := strings.Join(append([]string{\"docker\"}, allArgs...), \" \")\n\tlog.WithFields(\"cmd\", fullCmd).Trace(\"executing\")\n\n\tcmd := exec.Command(\"docker\", allArgs...)\n\tcmd.Env = os.Environ()\n\n\tcmd.Stdout = os.Stdout\n\tcmd.Stderr = os.Stderr\n\tcmd.Stdin = os.Stdin\n\n\treturn cmd.Run()\n}\n\nfunc isDockerClientBinaryAvailable() bool {","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/wagoodman/dive/blob/d6c691947f8fda635c952a17ee3b7555379d58f0/dive/image/docker/cli.go#L1-L34","documentation":"Returned by runDockerCmd (dive/image/docker/cli.go:16) when isDockerClientBinaryAvailable() cannot find a 'docker' executable on PATH. dive shells out to the docker CLI for interactive operations (build/push-style flows in a TTY), so the client binary itself is a hard dependency for those paths.","triggerScenarios":"Any code path reaching runDockerCmd (build flow via the docker engine resolver) on a host where exec.LookPath(\"docker\") fails: docker not installed, installed but not on PATH (snap with broken PATH, container images without the CLI), or a docker shim/wrapper shadowed.","commonSituations":"Running dive inside a slim CI container that has a Docker socket mounted but no docker CLI; macOS where docker is installed but PATH in theCI job excludes /usr/local/bin; podman-only hosts using aliasing that does not provide a literal 'docker' binary.","solutions":["Install the docker CLI (e.g. apt-get install docker-cli) or ensure the existing binary is on PATH: docker --version must succeed in the same shell","In containers/CI, either install docker-cli or avoid the build flow entirely: pre-build the image and analyze with dive docker://<image> (which uses the API client, not the CLI binary)","If only podman exists, run the build with podman and analyze the result via dive podman:// or a saved archive"],"exampleFix":"# before (CI step with only the socket mounted)\ndive build-image --build .\n\n# after (prebuilt image, no CLI dependency)\ndocker build -t app:ci .   # done in an earlier step or job\ndive docker://app:ci","handlingStrategy":"validation","validationCode":"// pre-flight: is the docker CLI actually reachable?\nif _, err := exec.LookPath(\"docker\"); err != nil {\n    return fmt.Errorf(\"docker CLI required for build flows; analyze a prebuilt image instead\")\n}","typeGuard":null,"tryCatchPattern":"err := resolver.Build(ctx, args)\nif err != nil && strings.Contains(err.Error(), \"cannot find docker client executable\") {\n    // install-time or env fix, not a retryable error\n    return fmt.Errorf(\"install docker-cli or set PATH; then re-run (hint: apt-get install docker.io or docker-cli)\")\n}","preventionTips":["Install the docker CLI in CI images that mount /var/run/docker.sock","Verify 'docker --version' works in the same shell/user dive runs as","For analysis-only runs, use dive docker://<image> which needs no CLI binary"],"tags":["docker","cli","environment","path","ci"],"backgroundTag":null,"analyzedSha":"d6c691947f8fda635c952a17ee3b7555379d58f0","analyzedAt":"2026-08-15T09:42:35.293Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}