AlistGo/alist · error · ErrArchiveIllegalPath

ErrArchiveIllegalPath

ErrArchiveIllegalPath

Error message

archive entry has illegal path: %s

What it means

Guard in internal/archive/tool/helper.go during generic archive walking: after directory entries are handled, any entry whose FileInfo mode is not regular is rejected with ErrArchiveIllegalPath. This is the shared helper used by archive tools, defending against special-file members before SecureJoin-destined extraction.

Source

Thrown at internal/archive/tool/helper.go:137

	var err error
	files := r.Files()
	if args.InnerPath == "/" {
		for i, file := range files {
			name := file.Name()
			info := file.FileInfo()
			if info.IsDir() {
				var dirPath string
				dirPath, err = SecureJoin(outputPath, name)
				if err != nil {
					return err
				}
				if err = os.MkdirAll(dirPath, 0700); err != nil {
					return err
				}
				continue
			}
			if !info.Mode().IsRegular() {
				return fmt.Errorf("%w: %s", ErrArchiveIllegalPath, name)
			}
			var dstPath string
			dstPath, err = SecureJoin(outputPath, name)
			if err != nil {
				return err
			}
			if err = os.MkdirAll(filepath.Dir(dstPath), 0700); err != nil {
				return err
			}
			err = _decompress(file, dstPath, args.Password, func(_ float64) {}, limiter)
			if err != nil {
				return err
			}
			up(float64(i+1) * 100.0 / float64(len(files)))
		}
	} else {
		innerPath := strings.TrimPrefix(args.InnerPath, "/")
		innerBase := stdpath.Base(innerPath)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Repack with dereferenced links (tar -h, cp -rL before zipping)
2. Use a system extractor that supports special files
3. Audit the archive listing first to identify the offending member names

Example fix

# inspect offending members first
# tar: tar tvf bundle.tgz | grep -E '^(l|c|b|p)'
# then repack with links followed: tar czfh bundle.tgz mydir/

func isSafeEntryMode(info fs.FileInfo) bool {
    return info.IsDir() || info.Mode().IsRegular()
}

if err := helper.Decompress(...); err != nil && errors.Is(err, tool.ErrArchiveIllegalPath) {
    // identify the member named in the error and quarantine the archive
}

When it happens

Trigger: Running Decompression via the archive tool on an archive containing symlinks/devices/FIFOs in the walked scope (non-inner-base path).

Common situations: Tar/zip archives from Unix systems containing links; backup archives; hostile archives.

Related errors

• ErrArchiveIllegalPath
• ErrArchiveIllegalPath
• ErrArchiveIllegalPath
• ErrArchiveIllegalPath
• total size of decompressed files exceeds the limit

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