wagoodman/dive · error

cannot find podman client executable

Error message

cannot find podman client executable

What it means

runPodmanCmd checks isPodmanClientBinaryAvailable() (a PATH lookup for the podman executable) before shelling out. If 'podman' cannot be found via exec.LookPath, every podman-engine command run through this helper returns this error immediately — no command is attempted.

Source

Thrown at dive/image/podman/cli.go:18

//go:build linux || darwin

package podman

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

// runPodmanCmd runs a given Podman command in the current tty
func runPodmanCmd(cmdStr string, args ...string) error {
	if !isPodmanClientBinaryAvailable() {
		return fmt.Errorf("cannot find podman 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("podman", allArgs...)
	cmd.Env = os.Environ()

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

	return cmd.Run()
}

func streamPodmanCmd(args ...string) (error, io.Reader) {

View on GitHub (pinned to d6c691947f)

Solutions

1. Install podman (e.g. 'apt install podman', 'brew install podman') and confirm 'podman --version' works in the same shell
2. If podman exists but isn't found, add its directory to PATH or symlink it into /usr/local/bin
3. If you actually meant to inspect a docker image, point dive at the docker source: 'dive --source docker <image>'
4. In containerized dive, mount the podman socket AND install the podman client in the image, or run dive on the host

Example fix

# before
dive --source podman myimg:latest   # cannot find podman client executable

# after
which podman || sudo apt-get install -y podman
podman --version
dive --source podman myimg:latest

// Fail fast before invoking any podman-source path.
if _, err := exec.LookPath("podman"); err != nil {
    return fmt.Errorf("podman client required: install podman or use the docker source")
}
// safe to run dive with --source podman now

if err := diveRunPodman(...); err != nil {
    if strings.Contains(err.Error(), "cannot find podman client executable") {
        // environment problem: install podman or switch source; do not retry unchanged
    }
}

When it happens

Trigger: Any dive code path that runs an interactive podman command (runPodmanCmd) while dive is configured to use the podman source (dive --source podman, or source selection in dive's config) on a machine where the podman binary is not installed or not on PATH.

Common situations: Running dive with podman engine inside a minimal container (dive's own docker image) that lacks the podman client; podman installed via snap/homebrew in a non-standard location not on PATH; CI images that only have docker; shells whose PATH was stripped (cron, systemd services).

Related errors

• cannot export analysis: %w
• unable to determine image source from %q: %v
• failed to unmarshal CI config file %s: %w
• directory for JSON export does not exist: %s
• file tree has path errors (use '--ignore-errors' to attempt

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