What causes "archive entry has illegal path: %s" in AlistGo/alist?

Repack the content as tar.gz/zip with symlinks dereferenced, or extract with unrar/7z which can materialize links safely

AlistGo/alist · error · ErrArchiveIllegalPath

ErrArchiveIllegalPath

ErrArchiveIllegalPath

Error message

archive entry has illegal path: %s

What it means

RAR-specific extraction guard in internal/archive/rardecode/rardecode.go. While iterating RAR entries (including inner-base handling for nested archives), any header whose Mode() is not a regular file — RAR symlink or special entries — is rejected with ErrArchiveIllegalPath before SecureJoin and decompression.

Source

Thrown at internal/archive/rardecode/rardecode.go:136

			if header.IsDir {
				name = name + "/"
			}
			if name == innerPath {
				if header.IsDir {
					if !createdBaseDir {
						baseDirPath, err = tool.SecureJoin(outputPath, innerBase)
						if err != nil {
							return err
						}
						if err = os.MkdirAll(baseDirPath, 0700); err != nil {
							return err
						}
						createdBaseDir = true
					}
					continue
				}
				if !header.Mode().IsRegular() {
					return fmt.Errorf("%w: %s", tool.ErrArchiveIllegalPath, header.Name)
				}
				dstPath, e := tool.SecureJoin(outputPath, stdpath.Base(innerPath))
				if e != nil {
					return e
				}
				if err = os.MkdirAll(filepath.Dir(dstPath), 0700); err != nil {
					return err
				}
				err = _decompress(reader, header, dstPath, up, limiter)
				if err != nil {
					return err
				}
				break
			} else if strings.HasPrefix(name, innerPath+"/") {
				if !createdBaseDir {
					baseDirPath, err = tool.SecureJoin(outputPath, innerBase)
					if err != nil {
						return err

View on GitHub (pinned to 843d9dc814)

Solutions

Repack the content as tar.gz/zip with symlinks dereferenced, or extract with unrar/7z which can materialize links safely
If you produced the rar, disable storing symlinks when archiving
Keep the guard intact; it prevents link-based escape during extraction

Example fix

# before: rar stores symlinks
rar a -ol data.rar mydir/

# after: dereference links before packing (or use tar)
cp -rL mydir mydir-flat && rar a data.rar mydir-flat/

Defensive patterns

Strategy: validation

Type guard

func rarHeaderSafe(h *rardecode.FileHeader) bool {
    return h.IsDir || h.Mode().IsRegular()
}

Try / catch

if err := rarTool.Decompress(ss, out, args, up); err != nil {
    if errors.Is(err, tool.ErrArchiveIllegalPath) {
        // symlink/device member in the rar: quarantine, do not retry
    }
}

Prevention

Check rars with 'unrar l -v' for symlink entries before extraction
Create rars without storing links when targeting this extractor
Prefer zip/tar workflows with dereferenced links for distribution

When it happens

Trigger: Decompressing a .rar archive (folder extraction path) that contains Unix symlink entries or other non-regular file types stored by the archiver.

Common situations: RAR archives created on Linux with symlinks preserved (WinRAR '-ol' style behavior); software distribution rars containing links; maliciously crafted rars.

Related errors

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