{"record":{"id":"2e9a2e4e9501746c","repo":"vxcontrol/pentagi","slug":"failed-to-initialize-docker-client-w","errorCode":null,"errorMessage":"failed to initialize docker client: %w","messagePattern":"failed to initialize docker client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"backend/pkg/docker/client.go","lineNumber":124,"sourceCode":"\n// GetPrimaryContainerPorts returns the host ports for a flow relative to\n// portsBase. A portsBase of 0 falls back to BaseContainerPortsNumber.\nfunc GetPrimaryContainerPorts(portsBase int, flowID int64) []int {\n\tif portsBase <= 0 || portsBase > (65535-limitContainerPortsNumber) {\n\t\tportsBase = BaseContainerPortsNumber\n\t}\n\tports := make([]int, containerPortsNumber)\n\tfor i := range containerPortsNumber {\n\t\tdelta := (int(flowID)*containerPortsNumber + i) % limitContainerPortsNumber\n\t\tports[i] = portsBase + delta\n\t}\n\treturn ports\n}\n\nfunc NewDockerClient(ctx context.Context, db database.Querier, cfg *config.Config) (DockerClient, error) {\n\tcli, err := client.New(client.FromEnv)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to initialize docker client: %w\", err)\n\t}\n\n\tinfoResult, err := cli.Info(ctx, client.InfoOptions{})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get docker info: %w\", err)\n\t}\n\tinfo := infoResult.Info\n\n\t// Resolve which host socket (if any) gets bind-mounted into worker containers.\n\t// Autodetection is skipped when DOCKER_INSIDE_HOST designates a daemon\n\t// endpoint for sandboxes: mounting the host socket alongside it would grant an\n\t// agent control of the daemon running PentAGI itself.\n\tsocket, autodetectSocket := cfg.WorkerDockerSocket()\n\tif autodetectSocket {\n\t\tsocket = getHostDockerSocket(ctx, cli)\n\t}\n\tinside := cfg.DockerInside\n\tif inside {","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/docker/client.go#L106-L142","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Mount the socket in docker-compose.yml: /var/run/docker.sock:/var/run/docker.sock, or set DOCKER_HOST to a reachable tcp:// endpoint.","Verify the daemon is up: docker ps on the host (or inside the container if configured).","Fix DOCKER_TLS_VERIFY/DOCKER_CERT_PATH: certs must exist and be readable by the process user; or unset TLS for a local socket.","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)."],"exampleFix":"// before (compose)\n# no docker socket, no DOCKER_HOST -> client.FromEnv fails\n// after (docker-compose.yml)\nservices:\n  backend:\n    environment:\n      - DOCKER_HOST=unix:///var/run/docker.sock\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock","handlingStrategy":"validation","validationCode":"// preflight before starting the app\nls -l /var/run/docker.sock            # socket exists and is readable?\necho \"DOCKER_HOST=$DOCKER_HOST\"       # unix:///var/run/docker.sock or tcp://host:2376\ndocker version                         # daemon reachable with these env vars?","typeGuard":null,"tryCatchPattern":"client, err := docker.NewDockerClient(ctx, db, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to initialize docker client\") {\n        return fmt.Errorf(\"docker unavailable: mount /var/run/docker.sock or set DOCKER_HOST/DOCKER_CERT_PATH correctly: %w\", err)\n    }\n    return err\n}","preventionTips":["Mount /var/run/docker.sock into the pentagi container in docker-compose.yml","Verify docker ps works with the same env the app will see","Keep DOCKER_TLS_VERIFY/DOCKER_CERT_PATH consistent with the endpoint type","Grant the process user socket access (docker group / SELinux label)"],"tags":["docker","configuration","environment","connectivity"],"backgroundTag":"docker-daemon-unavailable","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}