mkfs.erofs does not support tar mode (--tar option), disabli

Error message

mkfs.erofs does not support tar mode (--tar option), disabling erofs differ: %w

What it means

During erofs differ plugin init, if mkfs.erofs exists but does not support tar mode (the --tar option), the plugin returns plugin.ErrSkipPlugin wrapped in this message. This disables the erofs differ gracefully instead of failing runtime diffs. It signals the installed erofs-utils version is too old for tar-based snapshot generation.

Source

Thrown at plugins/diff/erofs/plugin/plugin.go:61

	// Linux only
	EnableDmverity bool `toml:"enable_dmverity"`
}

func init() {
	registry.Register(&plugin.Registration{
		Type: plugins.DiffPlugin,
		ID:   "erofs",
		Requires: []plugin.Type{
			plugins.MetadataPlugin,
		},
		Config: &Config{},
		InitFn: func(ic *plugin.InitContext) (any, error) {
			tarModeSupported, err := erofsutils.SupportGenerateFromTar()
			if err != nil {
				return nil, fmt.Errorf("failed to check mkfs.erofs availability: %v: %w", err, plugin.ErrSkipPlugin)
			}
			if !tarModeSupported {
				return nil, fmt.Errorf("mkfs.erofs does not support tar mode (--tar option), disabling erofs differ: %w", plugin.ErrSkipPlugin)
			}

			md, err := ic.GetSingle(plugins.MetadataPlugin)
			if err != nil {
				return nil, err
			}

			p := platforms.DefaultSpec()
			p.OS = "linux"
			ic.Meta.Platforms = append(ic.Meta.Platforms, p)
			// Select this differ for EROFS native images by default
			p.OSFeatures = []string{"erofs"}
			ic.Meta.Platforms = append(ic.Meta.Platforms, p)
			cs := md.(*metadata.DB).ContentStore()
			config := ic.Config.(*Config)

			var opts []erofs.DifferOpt

View on GitHub (pinned to 4246446a2b)

Solutions

Upgrade erofs-utils to a version supporting --tar (mkfs.erofs v1.6+ supports tar mode)
Confirm with `mkfs.erofs --help` that --tar is listed
Accept the skip if another differ (e.g. overlayfs) suffices

Example fix

// before: differ skipped
// after: upgrade tooling
# apt-get install -y erofs-utils  # ensure version with --tar support
$ mkfs.erofs --help | grep tar

Defensive patterns

Strategy: validation

Validate before calling

out, err := exec.Command("mkfs.erofs", "--help").CombinedOutput()
if err != nil || !strings.Contains(string(out), "--tar") {
    // mkfs.erofs too old; erofs differ will be skipped
}

Try / catch

if err := initErofsPlugin(); err != nil {
    var skip plugin.ErrSkipPlugin
    if errors.As(err, &skip) {
        log.Warn("erofs differ disabled", "cause", err)
    } else {
        return err
    }
}

Prevention

Pin erofs-utils >= version with --tar support in host images
Add a version check for mkfs.erofs to provisioning scripts
Keep overlayfs or another differ available as fallback

When it happens

Trigger: InitFn calling erofsutils.SupportGenerateFromTar() and getting tarModeSupported == false, i.e. mkfs.erofs output lacks the --tar flag.

Common situations: Distributions shipping older erofs-utils versions without --tar support; minimal base images with an outdated mkfs.erofs.

Related errors

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