vxcontrol/pentagi · error

list command failed for '%s' with exit code %d: %s

Error message

list command failed for '%s' with exit code %d: %s

What it means

The `find <dir> -maxdepth 1 -mindepth 1 ! -name .* -print0` command executed inside the container exited non-zero. The output captured so far is embedded in the message to aid diagnosis. Common exit codes: 1 = find error (e.g. directory vanished, permission), 125 = docker daemon failed to run the exec, 126 = binary not executable, 127 = command (find) not found.

Source

Thrown at backend/pkg/docker/client.go:1011

		return ContainerDirListing{}, fmt.Errorf("failed to create list exec for '%s': %w", dirPath, err)
	}

	resp, err := dc.ContainerExecAttach(ctx, createResp.ID, client.ExecAttachOptions{})
	if err != nil {
		return ContainerDirListing{}, fmt.Errorf("failed to attach list exec for '%s': %w", dirPath, err)
	}
	output, readErr := demuxExecStdout(resp.Reader, maxListStdoutBytes)
	resp.Close()
	if readErr != nil {
		return ContainerDirListing{}, fmt.Errorf("failed to read list output for '%s': %w", dirPath, readErr)
	}

	inspect, err := dc.ContainerExecInspect(ctx, createResp.ID)
	if err != nil {
		return ContainerDirListing{}, fmt.Errorf("failed to inspect list exec for '%s': %w", dirPath, err)
	}
	if inspect.ExitCode != 0 {
		return ContainerDirListing{}, fmt.Errorf("list command failed for '%s' with exit code %d: %s", dirPath, inspect.ExitCode, string(output))
	}

	entryPaths, truncated := parseFindEntries(output)

	stats, failures := statContainerEntries(ctx, entryPaths, containerListWorkers, func(ctx context.Context, entryPath string) (container.PathStat, error) {
		return dc.ContainerStatPath(ctx, containerID, entryPath)
	})

	// A cancelled context is a directory-level fault (the client is gone), not a
	// partial listing, so surface it as an error. Entries that individually failed
	// to stat are carried in Failures — the find exec already proved the container
	// alive, so a live directory degrades rather than 500s even if every entry failed.
	if err := ctx.Err(); err != nil {
		return ContainerDirListing{}, fmt.Errorf("listing container directory '%s': %w", dirPath, err)
	}

	listing := ContainerDirListing{Files: stats, Truncated: truncated}
	for _, f := range failures {

View on GitHub (pinned to ea665308ba)

Solutions

  1. Read the embedded output/exit code: 127 means install `find` (busybox) in the image
  2. Re-check the directory exists and is readable (`ls -ld <dir>` inside the container) and retry
  3. If permissions are the cause, run the exec as root or relax the directory mode
  4. Check for security modules (AppArmor/SELinux) denying exec in the container

Example fix

// before: distroless image has no find -> exit 127
FROM gcr.io/distroless/base
// after: use an image with a shell toolchain, or install busybox
FROM alpine:3 # provides busybox find
Defensive patterns

Strategy: validation

Validate before calling

// ensure `find` exists and the dir is readable inside the container
exec := []string{"sh", "-c", "command -v find >/dev/null && test -r " + dir + " && test -d " + dir}
if err := runInContainer(ctx, containerID, exec); err != nil {
    return fmt.Errorf("dir %s not listable in %s: %w", dir, containerID, err)
}

Try / catch

listing, err := client.ListContainerDir(ctx, containerID, dir)
if err != nil {
    var exitErr interface{ ExitCode() string }
    if code := extractExitCode(err); code == 127 {
        return fmt.Errorf("image lacks find binary; install busybox")
    }
    return err
}

Prevention

When it happens

Trigger: dirPath was deleted between the initial stat and the exec; the directory lacks read permission; the image has no `find` binary (exit 127); daemon failed to start the process (exit 125).

Common situations: Temp dirs cleaned by the workload mid-listing; minimal/distroless images without find; permission-restricted directories (chmod 000); SELinux/AppArmor blocking exec inside hardened containers.

Related errors

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/ec2e5f4796531737. Report an issue: GitHub.