containerd/containerd · error

root_path is required

Error message

root_path is required

What it means

Validate() in the devmapper snapshotter config collects all missing/invalid field errors and joins them. This error means the RequiredDevicePathRoot 'root_path' field was left empty in the plugin configuration. The library refuses to build a snapshotter without knowing where device-mapper state should live.

Source

Thrown at plugins/snapshots/devmapper/config.go:108

	if c.FileSystemType == "" {
		c.FileSystemType = fsTypeExt4
	}

	c.BaseImageSizeBytes = uint64(baseImageSize)
	return nil
}

// Validate makes sure configuration fields are valid
func (c *Config) Validate() error {
	var result []error

	if c.PoolName == "" {
		result = append(result, fmt.Errorf("pool_name is required"))
	}

	if c.RootPath == "" {
		result = append(result, fmt.Errorf("root_path is required"))
	}

	if c.BaseImageSize == "" {
		result = append(result, fmt.Errorf("base_image_size is required"))
	}

	if c.FileSystemType != "" {
		switch c.FileSystemType {
		case fsTypeExt4, fsTypeXFS, fsTypeExt2:
		default:
			result = append(result, fmt.Errorf("unsupported Filesystem Type: %q", c.FileSystemType))
		}
	} else {
		result = append(result, fmt.Errorf("filesystem type cannot be empty"))
	}

	return errors.Join(result...)
}

View on GitHub (pinned to 4246446a2b)

Solutions

1. Set root_path in the devmapper plugin configuration (e.g. /var/lib/containerd/devmapper) before loading.
2. Verify the config file/env mapping actually populates RootPath (check key spelling root_path).
3. Run LoadConfig/Validate early at startup so the missing field fails fast with the joined error list.
4. Constructing configs in Go: set RootPath explicitly instead of relying on zero values.

Example fix

// before
{"plugin":{"config":{"pool_name":"containerd-pool"}}}
// after
{"plugin":{"config":{"pool_name":"containerd-pool","root_path":"/var/lib/containerd/devmapper"}}}

func validateRootPath(cfg Config) error {
    if cfg.RootPath == "" {
        return errors.New("config: root_path must be set (e.g. /var/lib/containerd/devmapper)")
    }
    if err := os.MkdirAll(cfg.RootPath, 0o700); err != nil {
        return fmt.Errorf("root_path not usable: %w", err)
    }
    return nil
}

cfg, err := LoadConfig()
var cfgErr *ConfigError
if errors.As(err, &cfgErr) { /* inspect joined field errors for root_path */ }

When it happens

Trigger: Calling LoadConfig or NewSnapshotter with a config struct whose RootPath field is the empty string; also surfaced by TestFieldValidation/TestExistingPoolFieldValidation when exercising Validate with unset fields.

Common situations: Operators omit root_path in the plugin config JSON, env-var/flag mapping silently fails to populate RootPath, or code constructs config.Config{} programmatically and forgets to set RootPath.

Related errors

• base_image_size is required
• filesystem type cannot be empty
• failed to parse base image size: '%s': %w
• pool_name is required
• unsupported Filesystem Type: %q

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