AlistGo/alist · error

paths is required

Error message

paths is required

What it means

Thrown by the Alias driver's Init when the Addition.Paths configuration field is empty. The alias driver mounts other storages' sub-paths under virtual names, and without at least one 'name: target-path' pair there is nothing to mount, so initialization refuses to proceed.

Source

Thrown at drivers/alias/driver.go:34

type Alias struct {
	model.Storage
	Addition
	pathMap     map[string][]string
	autoFlatten bool
	oneKey      string
}

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

func (d *Alias) GetAddition() driver.Additional {
	return &d.Addition
}

func (d *Alias) Init(ctx context.Context) error {
	if d.Paths == "" {
		return errors.New("paths is required")
	}
	d.pathMap = make(map[string][]string)
	for _, path := range strings.Split(d.Paths, "\n") {
		path = strings.TrimSpace(path)
		if path == "" {
			continue
		}
		k, v := getPair(path)
		d.pathMap[k] = append(d.pathMap[k], v)
	}
	if len(d.pathMap) == 1 {
		for k := range d.pathMap {
			d.oneKey = k
		}
		d.autoFlatten = true
	} else {
		d.oneKey = ""
		d.autoFlatten = false

View on GitHub (pinned to 843d9dc814)

Solutions

1. Fill Paths with at least one line in the format 'alias_name: /mounted-storage/sub/path' (one per line) and re-save the storage
2. Trim the field and verify it contains a non-empty line before calling Init/driver add
3. If paths were lost during config migration, restore them from a storage-config backup before restarting

Example fix

# before (Addition.Paths)
""

# after — one mapping per line
photos: /onedrive/Pictures
work: /s3ftp/shared/reports

// Validate Paths before adding the Alias storage
lines := strings.Split(strings.TrimSpace(addition.Paths), "\n")
valid := 0
for _, l := range lines {
    if strings.TrimSpace(l) != "" && strings.Contains(l, ":") {
        valid++
    }
}
if valid == 0 {
    return errors.New("paths is required: add at least one 'name: /storage/sub' line")
}

null

null

When it happens

Trigger: Adding an Alias storage mount with an empty or whitespace-only Paths field; Paths containing only blank lines (they are all skipped, leaving pathMap empty even though the initial string check passed only for the fully-empty case).

Common situations: UI form submitted without filling the paths textarea; config migration/export dropped the multi-line field; YAML/JSON storage config where newline-separated paths got collapsed to empty; trailing-whitespace-only entries after editing.

Related errors

• owner and repo are required
• paths is required
• EncryptedSuffix is Illegal
• same-name dirs cannot make sub-dir
• same-name files cannot be moved

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