lima-vm/lima · info

skipped to download

Error message

skipped to download

What it means

ErrSkipped is a sentinel error returned by pkg/fileutils (DownloadFile, Errors, Prepare) when the downloader did not even attempt to download the specified file — most typically because the file's architecture does not match the expected architecture. Callers use errors.Is to filter it out as a non-fatal condition.

Source

Thrown at pkg/fileutils/download.go:19

// SPDX-FileCopyrightText: Copyright The Lima Authors
// SPDX-License-Identifier: Apache-2.0

package fileutils

import (
	"context"
	"errors"
	"fmt"
	"path"

	"github.com/sirupsen/logrus"

	"github.com/lima-vm/lima/v2/pkg/downloader"
	"github.com/lima-vm/lima/v2/pkg/limatype"
)

// ErrSkipped is returned when the downloader did not attempt to download the specified file.
var ErrSkipped = errors.New("skipped to download")

// DownloadFile downloads a file to the cache, optionally copying it to the destination. Returns path in cache.
func DownloadFile(ctx context.Context, dest string, f limatype.File, decompress bool, description string, expectedArch limatype.Arch, supportedImageFormats []string) (string, error) {
	if f.Arch != expectedArch {
		return "", fmt.Errorf("%w: %#q: unsupported arch: %#q", ErrSkipped, f.Location, f.Arch)
	}
	fields := logrus.Fields{"location": f.Location, "arch": f.Arch, "digest": f.Digest}
	logrus.WithFields(fields).Infof("Attempting to download %s", description)
	opts := []downloader.Opt{
		downloader.WithCache(),
		downloader.WithDecompress(decompress),
		downloader.WithDescription(fmt.Sprintf("%s (%s)", description, path.Base(f.Location))),
		downloader.WithExpectedDigest(f.Digest),
	}
	if len(supportedImageFormats) > 0 {
		opts = append(opts, downloader.WithImageFormats(supportedImageFormats))
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the wrapped message (`unsupported arch`) and pick a file.Location matching the expected arch
2. Update the template/YAML to an arch-appropriate image URL
3. If aggregating, filter with errors.Is(err, fileutils.ErrSkipped) instead of treating it as fatal
4. Verify the expected arch parameter passed to DownloadFile matches your instance

Example fix

// before
if err != nil { return err } // treats skip as fatal
// after
if err != nil && !errors.Is(err, fileutils.ErrSkipped) { return err }

// compare archs before download
if f.Arch != expectedArch {
    // choose a different file entry or skip intentionally
}

func isSkipped(err error) bool { return errors.Is(err, fileutils.ErrSkipped) }

path, err := fileutils.DownloadFile(ctx, dest, f, decompress, desc, arch, formats)
if err != nil {
    if errors.Is(err, fileutils.ErrSkipped) {
        log.Infof("skipped (not applicable): %v", err)
        return nil // not fatal
    }
    return err
}

When it happens

Trigger: DownloadFile is called with a limatype.File whose f.Arch != expectedArch; Prepare/EnsureFs aggregate results where one or more files were skipped for arch mismatch.

Common situations: Pulling an image/archive template whose location lists a different arch than the host/instance arch (e.g. x86_64 image on arm64 host); multi-arch file lists where only some entries apply.

Related errors

• %w: %#q: unsupported arch: %#q
• %v
• cache did not contain %#q
• failed to download %#q: %w
• cache did not contain %#q: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/f03269d874a1a359. Report an issue: GitHub.