vxcontrol/pentagi · critical

failed to initialize docker client: %w

Error message

failed to initialize docker client: %w

What it means

NewDockerClient builds a Docker client with client.FromEnv (DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH, and the mounted /var/run/docker.sock) and immediately validates it with a Ping/Info call. This error means client initialization itself failed — the Docker endpoint is misconfigured, the socket is missing/unreadable, or the daemon is not running. PentAGI needs Docker to spawn sandboxed tool containers, so startup aborts.

Source

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

// GetPrimaryContainerPorts returns the host ports for a flow relative to
// portsBase. A portsBase of 0 falls back to BaseContainerPortsNumber.
func GetPrimaryContainerPorts(portsBase int, flowID int64) []int {
	if portsBase <= 0 || portsBase > (65535-limitContainerPortsNumber) {
		portsBase = BaseContainerPortsNumber
	}
	ports := make([]int, containerPortsNumber)
	for i := range containerPortsNumber {
		delta := (int(flowID)*containerPortsNumber + i) % limitContainerPortsNumber
		ports[i] = portsBase + delta
	}
	return ports
}

func NewDockerClient(ctx context.Context, db database.Querier, cfg *config.Config) (DockerClient, error) {
	cli, err := client.New(client.FromEnv)
	if err != nil {
		return nil, fmt.Errorf("failed to initialize docker client: %w", err)
	}

	infoResult, err := cli.Info(ctx, client.InfoOptions{})
	if err != nil {
		return nil, fmt.Errorf("failed to get docker info: %w", err)
	}
	info := infoResult.Info

	// Resolve which host socket (if any) gets bind-mounted into worker containers.
	// Autodetection is skipped when DOCKER_INSIDE_HOST designates a daemon
	// endpoint for sandboxes: mounting the host socket alongside it would grant an
	// agent control of the daemon running PentAGI itself.
	socket, autodetectSocket := cfg.WorkerDockerSocket()
	if autodetectSocket {
		socket = getHostDockerSocket(ctx, cli)
	}
	inside := cfg.DockerInside
	if inside {

View on GitHub (pinned to ea665308ba)

Solutions

1. Mount the socket in docker-compose.yml: /var/run/docker.sock:/var/run/docker.sock, or set DOCKER_HOST to a reachable tcp:// endpoint.
2. Verify the daemon is up: docker ps on the host (or inside the container if configured).
3. Fix DOCKER_TLS_VERIFY/DOCKER_CERT_PATH: certs must exist and be readable by the process user; or unset TLS for a local socket.
4. Check socket permissions (add the process user to the docker group / adjust SELinux label) and re-check DOCKER_HOST syntax (e.g. unix:///var/run/docker.sock).

Example fix

// before (compose)
# no docker socket, no DOCKER_HOST -> client.FromEnv fails
// after (docker-compose.yml)
services:
  backend:
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

// preflight before starting the app
ls -l /var/run/docker.sock            # socket exists and is readable?
echo "DOCKER_HOST=$DOCKER_HOST"       # unix:///var/run/docker.sock or tcp://host:2376
docker version                         # daemon reachable with these env vars?

client, err := docker.NewDockerClient(ctx, db, cfg)
if err != nil {
    if strings.Contains(err.Error(), "failed to initialize docker client") {
        return fmt.Errorf("docker unavailable: mount /var/run/docker.sock or set DOCKER_HOST/DOCKER_CERT_PATH correctly: %w", err)
    }
    return err
}

When it happens

Trigger: main calls NewDockerClient; client.New(client.FromEnv) fails because DOCKER_HOST points to an unreachable/invalid endpoint, DOCKER_CERT_PATH files are missing or unreadable, /var/run/docker.sock is not mounted or lacks permissions, or the Docker daemon (dockerd) is not running.

Common situations: Running the backend outside Docker Compose without DOCKER_HOST set while no local socket exists; the pentagi container not mounted with /var/run/docker.sock; SELinux/AppArmor denying socket access; a remote DOCKER_HOST (tcp://) with wrong TLS cert paths; forgetting to install/start Docker Desktop.

Related errors

• Internal
• failed to create resources directory: %w
• container runtime check failed: %w
• token validation disabled with default salt
• Token.CreationDisabled

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