{"record":{"id":"fd81e94bf13021b6","repo":"abiosoft/colima","slug":"error-during-image-download-w","errorCode":null,"errorMessage":"error during image download: %w","messagePattern":"error during image download: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"environment/vm/lima/limautil/image.go","lineNumber":165,"sourceCode":"\t\t}\n\t\tfiles[arch.GoArch()] = file\n\n\t\tdiskImageMap[runtime] = files\n\t}\n\n\treturn nil\n}\n\n// downloadImage downloads the file and returns the location of the downloaded file.\nfunc downloadImage(host environment.HostActions, file limaconfig.File) (string, error) {\n\t// download image\n\trequest := downloader.Request{URL: file.Location}\n\tif file.Digest != \"\" {\n\t\trequest.SHA = &downloader.SHA{Size: 512, Digest: file.Digest}\n\t}\n\tlocation, err := downloader.Download(host, request)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"error during image download: %w\", err)\n\t}\n\n\treturn location, nil\n}\n\n// qcow2ToRaw uses qemu-img to conver the image from qcow to raw.\n// Returns the filename of the raw file and an error (if any).\nfunc qcow2ToRaw(host environment.Host, image diskImageFile) (string, error) {\n\tif _, err := os.Stat(image.Raw()); err == nil {\n\t\t// already exists, return\n\t\treturn image.Raw(), nil\n\t}\n\n\terr := host.Run(\"qemu-img\", \"convert\", \"-f\", \"qcow2\", \"-O\", \"raw\", image.String(), image.Raw())\n\tif err != nil {\n\t\t// remove the incomplete raw file\n\t\t_ = host.RunQuiet(\"rm\", \"-f\", image.Raw())\n\t\treturn \"\", err","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/environment/vm/lima/limautil/image.go#L147-L183","documentation":"Wrapped error returned by downloadImage when downloader.Download fails to fetch the VM disk image. The request carries the image URL and, when known, a sha512 digest; failure covers network errors, HTTP failures (404/403), and digest verification mismatches.","triggerScenarios":"Calling DownloadImage with no internet, through a breaking proxy, with a mirror that returns 404 (mirrorURL swaps the https://github.com prefix for the mirror), or when the downloaded bytes fail the embedded sha512 check.","commonSituations":"Corporate proxy/MITM certificate breaking the GitHub asset download; misconfigured image mirror; truncated download on flaky Wi-Fi causing checksum failure; GitHub outage during first 'colima start'.","solutions":["Check connectivity to the image URL (curl -I) and fix proxy/DNS/VPN","If using an image mirror, verify it actually serves the path that replaced the github.com prefix, or drop the mirror setting","Clear the partial download from the downloader cache and retry 'colima start'","Retry later if GitHub is having an incident"],"exampleFix":"# before: mirror 404 -> error during image download\nexport COLIMA_IMAGE_MIRROR=https://mirror.example.com\n# after: use a mirror that mirrors github release assets, or unset it\nunset COLIMA_IMAGE_MIRROR","handlingStrategy":"retry","validationCode":"// cheap pre-flight before the big download\nresp, err := http.Head(img.Location)\nif err != nil || resp.StatusCode >= 400 {\n    return fmt.Errorf(\"image URL unreachable (status %d): aborting before download\", resp.StatusCode)\n}","typeGuard":null,"tryCatchPattern":"Wrap DownloadImage in bounded retry with backoff; abort retries early if the cause is a digest mismatch (strings.Contains(err.Error(), \"sha512\") or \"digest\"), since retries cannot fix corruption — clear the cache instead.","preventionTips":["Validate mirrors actually mirror GitHub release assets before pointing colima at them","Keep the downloader cache clearable: know its location so a corrupt file can be removed","In CI, pre-cache the image artifact and run with the cache warm"],"tags":["download","network","image","checksum","proxy"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}