{"record":{"id":"9f27e189d94a08f6","repo":"containerd/containerd","slug":"failed-to-find-utilityvm-directory-in-base-layer","errorCode":null,"errorMessage":"failed to find UtilityVM directory in base layer %q: %w","messagePattern":"failed to find UtilityVM directory in base layer %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/snapshots/windows/common.go","lineNumber":212,"sourceCode":"}\n\n// Close closes the snapshotter\nfunc (w *windowsBaseSnapshotter) Close() error {\n\treturn w.ms.Close()\n}\n\n// This handles creating the UVMs scratch layer.\nfunc (w *windowsBaseSnapshotter) createUVMScratchLayer(ctx context.Context, snDir string, parentLayers []string) error {\n\tparentLen := len(parentLayers)\n\tif parentLen == 0 {\n\t\treturn errors.New(\"no parent layers present\")\n\t}\n\tbaseLayer := parentLayers[parentLen-1]\n\n\t// Make sure base layer has a UtilityVM folder.\n\tuvmPath := filepath.Join(baseLayer, \"UtilityVM\")\n\tif _, err := os.Stat(uvmPath); os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"failed to find UtilityVM directory in base layer %q: %w\", baseLayer, err)\n\t}\n\n\ttemplateDiffDisk := filepath.Join(uvmPath, \"SystemTemplate.vhdx\")\n\n\t// Check if SystemTemplate disk doesn't exist for some reason (this should be made during the unpacking\n\t// of the base layer).\n\tif _, err := os.Stat(templateDiffDisk); os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"%q does not exist in Utility VM image\", templateDiffDisk)\n\t}\n\n\t// Move the sandbox.vhdx into a nested vm folder to avoid clashing with a containers sandbox.vhdx.\n\tvmScratchDir := filepath.Join(snDir, \"vm\")\n\tif err := os.MkdirAll(vmScratchDir, 0777); err != nil {\n\t\treturn fmt.Errorf(\"failed to make `vm` directory for vm's scratch space: %w\", err)\n\t}\n\n\treturn copyScratchDisk(templateDiffDisk, filepath.Join(vmScratchDir, \"sandbox.vhdx\"))\n}","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/plugins/snapshots/windows/common.go#L194-L230","documentation":"createUVMScratchLayer builds a scratch layer for a Utility VM from a base Windows layer. It requires the base (last parent) layer to contain a UtilityVM directory; if os.Stat finds it missing, this error reports which base layer path lacks it. Utility VM images are only produced for Windows process/hypervisor-isolated base images that include the UVM components.","triggerScenarios":"Calling createUVMScratchLayer (via the anonymous snapshotter path) with parentLayers whose final entry has no UtilityVM subdirectory — i.e. the base image was not a proper Windows base layer with UVM support.","commonSituations":"Using a nanoserver/servercore variant or custom image without UtilityVM contents as the base for a hyper-v snapshotter; layer unpacking partially failed so UtilityVM was never written; pointing the snapshotter at the wrong parent layer list.","solutions":["Verify the base image is a Windows base layer that ships a UtilityVM directory (check the layer on disk)","Re-pull/re-extract the base image — a corrupted or partial unpack may have dropped UtilityVM","Ensure you are not mistakenly passing a non-base (child) layer as the last parent","Use an image built for the matching Windows build/hypervisor isolation scenario"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before invoking the UVM scratch path, verify the base layer\nuvmDir := filepath.Join(baseLayerPath, \"UtilityVM\")\nif fi, err := os.Stat(uvmDir); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"base layer %s lacks UtilityVM dir\", baseLayerPath)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to find UtilityVM directory\") {\n    return fmt.Errorf(\"image is not a Windows UVM-capable base layer: %w\", err)\n}","preventionTips":["Only use official Windows base images that include UtilityVM for hyper-v isolation","Verify image unpack completed successfully before creating UVM scratch layers","Pin image digests to known-good Windows base images","Match base image version to the host Windows build"],"tags":["windows","hyper-v","uvm","layers"],"backgroundTag":"missing-utilityvm-directory","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}