{"record":{"id":"29cd546a1f25f4e4","repo":"vxcontrol/pentagi","slug":"failed-to-pull-image-w","errorCode":null,"errorMessage":"failed to pull image: %w","messagePattern":"failed to pull image: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/docker/client.go","lineNumber":1189,"sourceCode":"\nfunc (dc *dockerClient) pullImage(ctx context.Context, imageName string) error {\n\tfilterArgs := make(client.Filters).Add(\"reference\", imageName)\n\timages, err := dc.client.ImageList(ctx, client.ImageListOptions{\n\t\tFilters: filterArgs,\n\t})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to list images: %w\", err)\n\t}\n\n\tif imageExistsLocally := len(images.Items) > 0; imageExistsLocally {\n\t\treturn nil\n\t}\n\n\tdc.logger.WithContext(ctx).WithField(\"image\", imageName).Info(\"initiating image download from registry...\")\n\n\tpullStream, err := dc.client.ImagePull(ctx, imageName, client.ImagePullOptions{})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to pull image: %w\", err)\n\t}\n\tdefer pullStream.Close()\n\n\t// drain pull stream to completion\n\tif _, err := io.Copy(io.Discard, pullStream); err != nil {\n\t\treturn fmt.Errorf(\"image download stream processing failed: %w\", err)\n\t}\n\n\tdc.logger.WithContext(ctx).WithField(\"image\", imageName).Debug(\"image pull completed\")\n\n\treturn nil\n}\n\nfunc getHostDockerSocket(ctx context.Context, cli *client.Client) string {\n\tdaemonHost := strings.TrimPrefix(cli.DaemonHost(), \"unix://\")\n\tif info, err := os.Stat(daemonHost); err != nil || info.IsDir() {\n\t\treturn defaultDockerSocketPath\n\t}","sourceCodeStart":1171,"sourceCodeEnd":1207,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/docker/client.go#L1171-L1207","documentation":"Returned by the Docker client's image pull helper when the initial call to the Docker daemon's ImagePull API fails. The underlying registry/daemon error (auth failure, missing tag, network problem) is wrapped via %w so errors.Is/As still work against the original cause.","triggerScenarios":"Calling the pull-image code path with an image name that does not exist in the registry, with bad/missing registry credentials, when the Docker daemon is unreachable, or when the registry is unreachable.","commonSituations":"Typo in image name or tag; image exists only in a private registry; `docker login` credentials not configured for the daemon host; Docker daemon stopped; corporate proxy/firewall blocking registry; DNS failure in the container host.","solutions":["Verify the image name and tag are correct and that the image exists in the registry","Check that registry credentials are available (docker login / auth config passed to ImagePullOptions)","Confirm the Docker daemon is running: `docker info`; restart it if needed","Test registry connectivity from the host (`docker pull <image>` manually)","Inspect the wrapped cause with errors.Is/As to see the exact daemon error"],"exampleFix":"// before\ndc.client.ImagePull(ctx, imageName, client.ImagePullOptions{})\n// after\nopts := client.ImagePullOptions{}\nif user != \"\" {\n    opts.RegistryAuth = encodeRegistryAuth(user, pass, registryHost)\n}\npullStream, err := dc.client.ImagePull(ctx, imageName, opts)","handlingStrategy":"try-catch","validationCode":"if err := validateImageName(imageName); err != nil { return err } // non-empty, has tag, registry reachable\nif !dockerDaemonReachable() { return errors.New(\"docker daemon unavailable\") }","typeGuard":"func isImagePullError(err error) bool { return strings.Contains(err.Error(), \"failed to pull image\") }","tryCatchPattern":"if err := dc.pullImage(ctx, imageName); err != nil {\n    var netErr net.Error\n    switch {\n    case errors.Is(err, context.DeadlineExceeded):\n        // retry with longer timeout\n    case errors.As(err, &netErr):\n        // check daemon/registry connectivity\n    default:\n        log.WithError(err).Error(\"image pull failed\")\n    }\n}","preventionTips":["Pre-pull required images during deployment warm-up","Pin image names and tags in config; validate them at startup","Ensure registry credentials are configured before starting flows","Monitor Docker daemon health before spawning flows"],"tags":["docker","image-pull","network"],"backgroundTag":"docker-image-pull-failed","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}