AlistGo/alist · error

no valid path mapping found

Error message

no valid path mapping found

What it means

After trimming and parsing the paths addition, parseAliases produced zero usable local->alias mappings, so Init rejects the config. This is different from error 265: the field was non-empty, but every entry failed parsing (bad separator, missing alias side, empty local path, or malformed line).

Source

Thrown at drivers/strm/driver.go:50

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

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

func (d *Strm) Init(ctx context.Context) error {
	if strings.TrimSpace(d.Paths) == "" {
		return errors.New("paths is required")
	}
	if d.SaveStrmToLocal && strings.TrimSpace(d.SaveStrmLocalPath) == "" {
		return errors.New("SaveStrmLocalPath is required")
	}

	d.aliases = parseAliases(d.Paths)
	if len(d.aliases) == 0 {
		return errors.New("no valid path mapping found")
	}

	d.autoFlatten = len(d.aliases) == 1
	d.singleRootKey = ""
	if d.autoFlatten {
		for k := range d.aliases {
			d.singleRootKey = k
		}
	}

	d.mediaExtSet = parseExtSet(defaultIfEmpty(d.FilterFileTypes, defaultMediaExt))
	d.downloadExtSet = parseExtSet(defaultIfEmpty(d.DownloadFileTypes, defaultDownloadExt))
	d.normalizedPrefix = normalizePrefix(defaultIfEmpty(d.PathPrefix, "/d"))
	d.normalizedMode = normalizeSaveMode(d.SaveLocalMode)

	if d.Version != 5 {
		d.FilterFileTypes = mergeDefaultExtCSV(d.FilterFileTypes, defaultMediaExt)
		d.DownloadFileTypes = mergeDefaultExtCSV(d.DownloadFileTypes, defaultDownloadExt)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Check the driver's documented mapping syntax and reformat each entry as localPath:alias
2. Open drivers/strm/util.go parseAliases to see exactly which shapes are accepted (e.g. how drive-letter colons are handled)
3. Test with a single minimal mapping first (/tmp/media:Media), confirm Init passes, then add the rest

Example fix

// before (addition)
"paths": "/mnt/movies"

// after
"paths": "/mnt/movies:Movies

aliases := parseAliases(addition.Paths)
if len(aliases) == 0 {
    return fmt.Errorf("no valid path mapping found in %q — expected entries like /local/dir:Alias", addition.Paths)
}

func validMappingEntry(entry string) bool {
    parts := strings.SplitN(entry, ":", 2)
    return len(parts) == 2 && strings.TrimSpace(parts[0]) != "" && strings.TrimSpace(parts[1]) != ""
}

When it happens

Trigger: Paths like 'justoneentry' (no ':' separator), '/a::', ':alias' (empty local side), or entries made only of separators/spaces — non-empty input that yields zero mappings.

Common situations: Wrong format assumed (user pastes a plain directory list instead of local:alias pairs); Windows paths with drive letters confusing the parser ('C:\media' split at the first colon); Copy-paste artifacts: trailing separators on every line, smart quotes, or empty lines depending on parser tolerance

Related errors

• paths is required
• SaveStrmLocalPath is required
• owner and repo are required
• api_login and api_key are required
• invalid line: %s, because file info must end with ':'

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