{"record":{"id":"f03269d874a1a359","repo":"lima-vm/lima","slug":"skipped-to-download","errorCode":null,"errorMessage":"skipped to download","messagePattern":"skipped to download","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"info","filePath":"pkg/fileutils/download.go","lineNumber":19,"sourceCode":"// SPDX-FileCopyrightText: Copyright The Lima Authors\n// SPDX-License-Identifier: Apache-2.0\n\npackage fileutils\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"path\"\n\n\t\"github.com/sirupsen/logrus\"\n\n\t\"github.com/lima-vm/lima/v2/pkg/downloader\"\n\t\"github.com/lima-vm/lima/v2/pkg/limatype\"\n)\n\n// ErrSkipped is returned when the downloader did not attempt to download the specified file.\nvar ErrSkipped = errors.New(\"skipped to download\")\n\n// DownloadFile downloads a file to the cache, optionally copying it to the destination. Returns path in cache.\nfunc DownloadFile(ctx context.Context, dest string, f limatype.File, decompress bool, description string, expectedArch limatype.Arch, supportedImageFormats []string) (string, error) {\n\tif f.Arch != expectedArch {\n\t\treturn \"\", fmt.Errorf(\"%w: %#q: unsupported arch: %#q\", ErrSkipped, f.Location, f.Arch)\n\t}\n\tfields := logrus.Fields{\"location\": f.Location, \"arch\": f.Arch, \"digest\": f.Digest}\n\tlogrus.WithFields(fields).Infof(\"Attempting to download %s\", description)\n\topts := []downloader.Opt{\n\t\tdownloader.WithCache(),\n\t\tdownloader.WithDecompress(decompress),\n\t\tdownloader.WithDescription(fmt.Sprintf(\"%s (%s)\", description, path.Base(f.Location))),\n\t\tdownloader.WithExpectedDigest(f.Digest),\n\t}\n\tif len(supportedImageFormats) > 0 {\n\t\topts = append(opts, downloader.WithImageFormats(supportedImageFormats))\n\t}\n","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/fileutils/download.go#L1-L37","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped message (`unsupported arch`) and pick a file.Location matching the expected arch","Update the template/YAML to an arch-appropriate image URL","If aggregating, filter with errors.Is(err, fileutils.ErrSkipped) instead of treating it as fatal","Verify the expected arch parameter passed to DownloadFile matches your instance"],"exampleFix":"// before\nif err != nil { return err } // treats skip as fatal\n// after\nif err != nil && !errors.Is(err, fileutils.ErrSkipped) { return err }","handlingStrategy":"type-guard","validationCode":"// compare archs before download\nif f.Arch != expectedArch {\n    // choose a different file entry or skip intentionally\n}","typeGuard":"func isSkipped(err error) bool { return errors.Is(err, fileutils.ErrSkipped) }","tryCatchPattern":"path, err := fileutils.DownloadFile(ctx, dest, f, decompress, desc, arch, formats)\nif err != nil {\n    if errors.Is(err, fileutils.ErrSkipped) {\n        log.Infof(\"skipped (not applicable): %v\", err)\n        return nil // not fatal\n    }\n    return err\n}","preventionTips":["Check f.Arch against the instance arch before downloading","Use errors.Is(err, fileutils.ErrSkipped) to filter skip results","Keep templates arch-aware or multi-arch"],"tags":["download","arch-mismatch","sentinel-error"],"backgroundTag":"download-skipped","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}