containerd/containerd · error

failed to sync tar2ext4 vhd to disk: %w

Error message

failed to sync tar2ext4 vhd to disk: %w

What it means

After a successful tar2ext4 conversion, Apply calls outFile.Sync() to flush the VHD to disk; a Sync failure is wrapped as 'failed to sync tar2ext4 vhd to disk'. This indicates the OS could not flush written data to stable storage, so the produced VHD may not be durable.

Source

Thrown at plugins/diff/lcow/lcow.go:164

	layerPath := path.Join(layer, "layer.vhd")
	outFile, err := os.Create(layerPath)
	if err != nil {
		return emptyDesc, err
	}
	defer func() {
		if err != nil {
			outFile.Close()
			os.Remove(layerPath)
		}
	}()

	err = tar2ext4.Convert(rc, outFile, tar2ext4.ConvertWhiteout, tar2ext4.AppendVhdFooter, tar2ext4.MaximumDiskSize(maxLcowVhdSizeGB))
	if err != nil {
		return emptyDesc, fmt.Errorf("failed to convert tar2ext4 vhd: %w", err)
	}
	err = outFile.Sync()
	if err != nil {
		return emptyDesc, fmt.Errorf("failed to sync tar2ext4 vhd to disk: %w", err)
	}
	outFile.Close()

	// Read any trailing data
	if _, err := io.Copy(io.Discard, rc); err != nil {
		return emptyDesc, err
	}

	err = security.GrantVmGroupAccess(layerPath)
	if err != nil {
		return emptyDesc, fmt.Errorf("failed GrantVmGroupAccess on layer vhd: %v: %w", layerPath, err)
	}

	return ocispec.Descriptor{
		MediaType: ocispec.MediaTypeImageLayer,
		Size:      rc.c,
		Digest:    digester.Digest(),
	}, nil

View on GitHub (pinned to 4246446a2b)

Solutions

1. Free disk space on the target volume and retry
2. Check disk health (SMART) and filesystem errors; run fsck/chkdsk if needed
3. Retry the Apply after resolving storage issues

Example fix

// before: sync fails, layer lost
// after: pre-check available space
if stat, err := outDirStat(); err == nil && stat.Available < requiredBytes {
    return fmt.Errorf("insufficient disk space")
}
err = outFile.Sync()

if stat, err := fs.Stat(volume); err == nil && stat free space < vhdSize {
    return fmt.Errorf("insufficient space for vhd sync")
}

err := applyLcowLayer(ctx, desc, mounts)
if err != nil && strings.Contains(err.Error(), "failed to sync tar2ext4 vhd to disk") {
    // check disk space/health, then retry once
    if freeSpaceOK() {
        err = applyLcowLayer(ctx, desc, mounts)
    }
    return err
}

When it happens

Trigger: outFile.Sync() returning an error after Convert succeeded — typically ENOSPC (disk full), EIO (disk fault), or invalid file state on the Windows/LCOW filesystem.

Common situations: Hosts running out of disk space mid-write; failing storage hardware; unusual mounts (e.g. network filesystems with sync issues).

Related errors

• failed to apply config opt: %w
• failed to convert tar2ext4 vhd: %w
• failed GrantVmGroupAccess on layer vhd: %v: %w
• windowsLcowDiff does not implement Compare method: %w
• number of mounts should always be 1 for Windows lcow-layers:

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/1076800dfa30eb48. Report an issue: GitHub.