AlistGo/alist · error

root folder %s not exists

Error message

root folder %s not exists

What it means

Init-time configuration error of the local-storage driver: the configured root folder (RootFolderPath) does not exist on disk (utils.Exists returns false), so the mount cannot start. This is checked before anything else runs, guaranteeing fail-fast on a bad path.

Source

Thrown at drivers/local/driver.go:65

	useFFmpeg bool
}

func (d *Local) Config() driver.Config {
	return config
}

func (d *Local) Init(ctx context.Context) error {
	if d.MkdirPerm == "" {
		d.mkdirPerm = 0777
	} else {
		v, err := strconv.ParseUint(d.MkdirPerm, 8, 32)
		if err != nil {
			return err
		}
		d.mkdirPerm = int32(v)
	}
	if !utils.Exists(d.GetRootPath()) {
		return fmt.Errorf("root folder %s not exists", d.GetRootPath())
	}
	if !filepath.IsAbs(d.GetRootPath()) {
		abs, err := filepath.Abs(d.GetRootPath())
		if err != nil {
			return err
		}
		d.Addition.RootFolderPath = abs
	}

	d.useFFmpeg = d.UseFFmpeg

	if d.ThumbCacheFolder != "" && !utils.Exists(d.ThumbCacheFolder) {
		err := os.MkdirAll(d.ThumbCacheFolder, os.FileMode(d.mkdirPerm))
		if err != nil {
			return err
		}
	}
	d.thumbSize = 144

View on GitHub (pinned to 843d9dc814)

Solutions

1. Verify the path with ls/stat on the machine/container where OpenList runs and fix the typo.
2. Create the directory first (mkdir -p /data/media) or point to an existing one.
3. In Docker, add/fix the volume mapping (-v /host/path:/container/path) and use the container path in storage config.
4. If the drive mounts late, ensure it is mounted before OpenList starts (systemd dependency or restart OpenList after mounting).

Example fix

# before: storage root_path = /mnt/media (does not exist in container)
# after
docker run -v /host/media:/mnt/media openlist:latest
# storage root_path = /mnt/media (now exists)

// Pre-flight before saving storage config
if _, err := os.Stat(rootPath); err != nil {
    return fmt.Errorf("root path %q not accessible: %w; create it or fix the mount", rootPath, err)
}
if !filepath.IsAbs(rootPath) {
    return errors.New("root path must be absolute")
}

func validLocalRoot(p string) bool {
    return filepath.IsAbs(p) && utils.Exists(p)
}

if err := storage.Init(ctx); err != nil {
    if strings.Contains(err.Error(), "not exists") {
        // surface a config-form error prompting the user for the path
        return renderPathError(err)
    }
}

When it happens

Trigger: Adding/editing a local storage whose root path is misspelled, on an unmounted/unplugged drive, inside a container without the bind-mount, or using a Windows-style path on Linux (or vice versa).

Common situations: Docker deployments where the host folder was not mounted into the container; typo or wrong case in the path; NFS/USB drive not mounted at boot before OpenList starts; moving the data directory without updating the storage config.

Related errors

• ref: %w
• owner and repo are required
• committer email is required
• committer name is required
• author email is required

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/2be463948e15c852. Report an issue: GitHub.