vxcontrol/pentagi · error

failed to list images: %w

Error message

failed to list images: %w

What it means

pullImage first calls ImageList with a `reference` filter to check whether the image already exists locally. This error wraps a failure of that listing API call, so the local-existence check could not be performed and the pull is aborted before even attempting a download.

Source

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

	return err
}

func (dc *dockerClient) CopyFromContainer(
	ctx context.Context,
	containerID string,
	srcPath string,
) (io.ReadCloser, container.PathStat, error) {
	result, err := dc.client.CopyFromContainer(ctx, containerID, client.CopyFromContainerOptions{SourcePath: srcPath})
	return result.Content, result.Stat, err
}

func (dc *dockerClient) pullImage(ctx context.Context, imageName string) error {
	filterArgs := make(client.Filters).Add("reference", imageName)
	images, err := dc.client.ImageList(ctx, client.ImageListOptions{
		Filters: filterArgs,
	})
	if err != nil {
		return fmt.Errorf("failed to list images: %w", err)
	}

	if imageExistsLocally := len(images.Items) > 0; imageExistsLocally {
		return nil
	}

	dc.logger.WithContext(ctx).WithField("image", imageName).Info("initiating image download from registry...")

	pullStream, err := dc.client.ImagePull(ctx, imageName, client.ImagePullOptions{})
	if err != nil {
		return fmt.Errorf("failed to pull image: %w", err)
	}
	defer pullStream.Close()

	// drain pull stream to completion
	if _, err := io.Copy(io.Discard, pullStream); err != nil {
		return fmt.Errorf("image download stream processing failed: %w", err)
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Verify daemon connectivity: `docker ps` succeeds from the same environment
2. Fix permissions on the Docker socket (add user to `docker` group) or use rootless mode correctly
3. Validate the imageName is a well-formed reference (registry/repo:tag) — malformed filters fail the list call
4. Retry with backoff if the daemon was temporarily unavailable

Example fix

// before: socket permission denied
images, err := dc.client.ImageList(ctx, opts) // fails
// after (host fix):
// sudo usermod -aG docker $USER && newgrp docker
images, err := dc.client.ImageList(ctx, opts) // succeeds

// validate image reference shape before calling
if ref, err := reference.ParseNormalizedNamed(imageName); err != nil {
    return fmt.Errorf("invalid image reference %q: %w", imageName, err)
} else {
    _ = ref
}

if err := pullImage(ctx, imageName); err != nil {
    if strings.Contains(err.Error(), "failed to list images") {
        // daemon-side issue: check connectivity then retry with backoff
        time.Sleep(2 * time.Second)
        return pullImage(ctx, imageName)
    }
    return err
}

When it happens

Trigger: dc.client.ImageList(ctx, client.ImageListOptions{Filters: filterArgs}) fails because the Docker daemon is unreachable, the socket is permission-denied, the reference filter string is malformed, or the daemon returned 500/timeout.

Common situations: DOCKER_HOST misconfigured or daemon not running; user not in the `docker` group (permission denied on /var/run/docker.sock); malformed image name (invalid tag/registry chars); remote daemon temporarily unavailable.

Related errors

• failed to pull default image '%s': %w
• docker exec systemerr: %s
• failed to pull image: %w
• failed to create exec process: %w
• container runtime check failed: %w

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