{"record":{"id":"45305303dce9579c","repo":"abiosoft/colima","slug":"disk-image-must-be-downloaded-from-s-hash-fail","errorCode":null,"errorMessage":"disk image must be downloaded from '%s', hash failure: %w","messagePattern":"disk image must be downloaded from '(.+?)', hash failure: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"environment/vm/lima/disk.go","lineNumber":165,"sourceCode":"\n\t// use a user specified disk image\n\tif conf.DiskImage != \"\" {\n\t\tif _, err := os.Stat(conf.DiskImage); err != nil {\n\t\t\treturn fmt.Errorf(\"invalid disk image: %w\", err)\n\t\t}\n\n\t\timage, err := limautil.Image(l.limaConf.Arch, conf.Runtime)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error getting disk image details: %w\", err)\n\t\t}\n\n\t\tsha := downloader.SHA{Size: 512, Digest: image.Digest}\n\t\tif err := sha.ValidateFile(l.host, conf.DiskImage); err != nil {\n\t\t\tif conf.ForceDiskImage != nil && *conf.ForceDiskImage {\n\t\t\t\tlog.Warnln(\"unable to validate disk image, but continuing as requested...\")\n\t\t\t\timage.Digest = \"\" // clear so lima does not re-validate\n\t\t\t} else {\n\t\t\t\treturn fmt.Errorf(\"disk image must be downloaded from '%s', hash failure: %w\", image.Location, err)\n\t\t\t}\n\t\t}\n\n\t\timage.Location = conf.DiskImage\n\t\tl.limaConf.Images = []limaconfig.File{image}\n\t\treturn nil\n\t}\n\n\t// use a previously cached image\n\tif image, ok := limautil.ImageCached(l.limaConf.Arch, conf.Runtime, conf.DiskImageMirror); ok {\n\t\tl.limaConf.Images = []limaconfig.File{image}\n\t\treturn nil\n\t}\n\n\t// download image\n\tlog.Infoln(\"downloading disk image ...\")\n\timage, err := limautil.DownloadImage(l.limaConf.Arch, conf.Runtime, conf.DiskImageMirror)\n\tif err != nil {","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/environment/vm/lima/disk.go#L147-L183","documentation":"A user-supplied disk image must be byte-identical to Colima's official image: downloader.SHA (SHA-512) validates the file against the digest from limautil.Image. A mismatch means the file is not the expected artifact (different version, corrupted download, modified image). Unless ForceDiskImage is set, provisioning fails rather than booting an unverified image.","triggerScenarios":"Passing --disk-image with a locally built, trimmed, re-compressed, or partially downloaded qcow2; supplying an image for a different Colima version than the embedded digest; truncated transfer. The error is skipped only when conf.ForceDiskImage is true (which logs a warning and clears the digest).","commonSituations":"Offline/air-gapped installs with hand-copied images; mirrors that re-encode artifacts; resumable-download corruption; teams pinning custom hardened images.","solutions":["Download the exact official image from the location named in the error and retry with that file.","If the custom image is intentional, bypass verification with the force flag (e.g. `colima start --disk-image /path --force-disk-image`) and accept the warning; the digest is cleared so Lima will not re-validate.","Re-verify the file yourself (`shasum -a 512 image`) against the expected digest to detect corruption, then re-download if it differs.","Upgrade/downgrade Colima so its embedded digest matches the image version you are supplying."],"exampleFix":"# before\ncolima start --disk-image ./my-customized.qcow2   # digest mismatch -> error\n\n# after\ncolima start --disk-image ./my-customized.qcow2 --force-disk-image   # warns and continues","handlingStrategy":"fallback","validationCode":"// pre-verify the SHA-512 before handing the file to colima\n// expected digest is published with the release artifact\nif !sha512Matches(diskImagePath, expectedDigest) {\n    if !forceDiskImage { log.Fatal(\"digest mismatch; re-download or pass --force-disk-image\") }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Download images only from the official location named in the error","Verify sha512 after every download/mirror copy","Use --force-disk-image only for intentionally customized images"],"tags":["disk-image","checksum","sha512","colima","verification"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}