{"record":{"id":"cbbb1d75ced16ee5","repo":"containerd/containerd","slug":"failed-to-create-base-vhd-w","errorCode":null,"errorMessage":"failed to create base vhd: %w","messagePattern":"failed to create base vhd: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/snapshots/windows/cimfs.go","lineNumber":424,"sourceCode":"\tif err != nil && !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"failed to stat diff VHD: %w\", err)\n\t} else if baseVHDExists && err == nil {\n\t\tdiffVHDExists = true\n\t} else {\n\t\t// remove this diff VHD, it must be recreated with the new base VHD.\n\t\tos.RemoveAll(diffVHDPath)\n\t}\n\n\tdefer func() {\n\t\tif err != nil {\n\t\t\tos.RemoveAll(baseVHDPath)\n\t\t\tos.RemoveAll(diffVHDPath)\n\t\t}\n\t}()\n\n\tif !baseVHDExists {\n\t\tif err = createScratchVHD(ctx, baseVHDPath, WithNTFSFormat()); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create base vhd: %w\", err)\n\t\t}\n\t}\n\n\tif !diffVHDExists {\n\t\t// Create the differencing disk that will be what's copied for the final rw layer\n\t\t// for a container.\n\t\tif err = vhd.CreateDiffVhd(diffVHDPath, baseVHDPath, vhdBlockSizeInBytes); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create differencing disk: %w\", err)\n\t\t}\n\t}\n\n\t// Grant VM group access to the differencing VHD (base VHD access is already granted by createSingleVHD)\n\tif err = security.GrantVmGroupAccess(diffVHDPath); err != nil {\n\t\treturn fmt.Errorf(\"failed to grant vm group access to %s: %w\", diffVHDPath, err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":406,"sourceCodeEnd":442,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/plugins/snapshots/windows/cimfs.go#L406-L442","documentation":"The base scratch VHD could not be created by createScratchVHD (with NTFS formatting) when it did not already exist. createDifferencingScratchVHDs wraps the underlying failure — which itself may be an option-application error, stat failure, or a vhd.CreateVirtualDisk/format failure — and cleanup removes partial files afterward.","triggerScenarios":"First snapshotter init (baseVHDExists==false) calls createScratchVHD(ctx, baseVHDPath, WithNTFSFormat()); the underlying vhd.CreateVirtualDisk, VHD mount/format step, or an option callback fails (no disk space, Virtual Disk Service unavailable, insufficient privileges).","commonSituations":"Disk full on the containerd volume; Windows Virtual Disk Service (vds) or vhdx APIs blocked by policy/security software; running containerd without required privileges; file already exists as a corrupt leftover handled by the wrong branch.","solutions":["Unwrap to the root cause from createScratchVHD and fix it (space, permissions, VDS availability).","Free disk space on the volume hosting the snapshotter root.","Ensure containerd runs elevated enough to create virtual disks (Virtual Disk APIs).","Check that security software isn't blocking vhd image creation; delete any corrupt leftover base VHD and restart containerd."],"exampleFix":"// before: full disk\n// after: free space then re-init\n// Get-Volume C  # verify free space\n// Restart-Service containerd","handlingStrategy":"validation","validationCode":"func precheckBaseVHDCreation(baseVHDPath string, needBytes uint64) error {\n    if fi, err := os.Stat(filepath.Dir(baseVHDPath)); err != nil || !fi.IsDir() {\n        return fmt.Errorf(\"scratch dir missing or invalid\")\n    }\n    if free, err := freeDiskSpace(filepath.VolumeName(baseVHDPath)); err != nil || free < needBytes {\n        return fmt.Errorf(\"insufficient space for base VHD\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := createScratchVHD(ctx, baseVHDPath, WithNTFSFormat()); err != nil {\n    if errors.Is(err, os.ErrExist) { os.Remove(baseVHDPath); retry() }\n    else if isDiskFull(err) { freeSpace(); retry() }\n    else { return fmt.Errorf(\"cannot create base vhd, check VDS/privileges: %w\", err) }\n}","preventionTips":["Ensure adequate free space before starting containerd.","Run containerd with privileges sufficient for Virtual Disk API calls.","Verify policy/security software permits vhdx creation.","Let the built-in cleanup (RemoveAll on error) finish before re-running init."],"tags":["windows","vhdx","disk","cimfs","snapshotter-init"],"backgroundTag":"base-vhd-creation-failed","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}