wagoodman/dive · error

cannot find docker client executable

Error message

cannot find docker client executable

What it means

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.

Source

Thrown at dive/image/docker/cli.go:16

package docker

import (
	"fmt"
	"github.com/wagoodman/dive/internal/log"
	"github.com/wagoodman/dive/internal/utils"
	"os"
	"os/exec"
	"strings"
)

// runDockerCmd runs a given Docker command in the current tty
func runDockerCmd(cmdStr string, args ...string) error {

	if !isDockerClientBinaryAvailable() {
		return fmt.Errorf("cannot find docker client executable")
	}

	allArgs := utils.CleanArgs(append([]string{cmdStr}, args...))

	fullCmd := strings.Join(append([]string{"docker"}, allArgs...), " ")
	log.WithFields("cmd", fullCmd).Trace("executing")

	cmd := exec.Command("docker", allArgs...)
	cmd.Env = os.Environ()

	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	cmd.Stdin = os.Stdin

	return cmd.Run()
}

func isDockerClientBinaryAvailable() bool {

View on GitHub (pinned to d6c691947f)

Solutions

1. 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
2. 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)
3. If only podman exists, run the build with podman and analyze the result via dive podman:// or a saved archive

Example fix

# before (CI step with only the socket mounted)
dive build-image --build .

# after (prebuilt image, no CLI dependency)
docker build -t app:ci .   # done in an earlier step or job
dive docker://app:ci

// pre-flight: is the docker CLI actually reachable?
if _, err := exec.LookPath("docker"); err != nil {
    return fmt.Errorf("docker CLI required for build flows; analyze a prebuilt image instead")
}

err := resolver.Build(ctx, args)
if err != nil && strings.Contains(err.Error(), "cannot find docker client executable") {
    // install-time or env fix, not a retryable error
    return fmt.Errorf("install docker-cli or set PATH; then re-run (hint: apt-get install docker.io or docker-cli)")
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• evaluation failed
• failed to unmarshal CI config file %s: %w
• could not determine docker host: %v
• cannot find podman client executable
• no results returned

AI-assisted analysis of wagoodman/dive@d6c691947f (2026-08-15). Data as JSON: /api/errors/d641860bf4ed4999. Report an issue: GitHub.