AlistGo/alist · error · ErrArchiveIllegalPath

ErrArchiveIllegalPath

ErrArchiveIllegalPath

Error message

archive entry has illegal path: %s

What it means

Second guard in the archives decompression path: decompress() in internal/archive/archives/utils.go opens the entry from the virtual fs.FS and stats it before writing; a mode that is not a regular file (symlink, device, FIFO) triggers ErrArchiveIllegalPath. It complements the WalkDir check by re-validating at the actual copy step.

Source

Thrown at internal/archive/archives/utils.go:74

func filterPassword(err error) error {
	if err != nil && strings.Contains(err.Error(), "password") {
		return errs.WrongArchivePassword
	}
	return err
}

func decompress(fsys fs2.FS, filePath, dstPath string, up model.UpdateProgress, limiter *tool.SizeLimiter) error {
	rc, err := fsys.Open(filePath)
	if err != nil {
		return err
	}
	defer rc.Close()
	stat, err := rc.Stat()
	if err != nil {
		return err
	}
	if !stat.Mode().IsRegular() {
		return fmt.Errorf("%w: %s", tool.ErrArchiveIllegalPath, filePath)
	}
	f, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
	if err != nil {
		return err
	}
	defer f.Close()
	_, err = utils.CopyWithBuffer(limiter.WrapWriter(f), &stream.ReaderUpdatingProgress{
		Reader: &stream.SimpleReaderWithSize{
			Reader: rc,
			Size:   stat.Size(),
		},
		UpdateProgress: up,
	})
	return err
}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Repack the archive with special entries dereferenced or omitted
2. Use an external extractor when preserving symlinks/devices is a requirement
3. Verify integrity of the archive (re-download) if the entry type looks corrupted

func isRegularMode(m fs.FileMode) bool { return m.IsRegular() }

if err := decompress(fsys, p, dstPath, up, limiter); err != nil {
    if errors.Is(err, tool.ErrArchiveIllegalPath) {
        return fmt.Errorf("unsafe member %q: %w", p, err)
    }
    return err
}

When it happens

Trigger: Extracting any archive through the Archives tool where the entry being copied (single-file extraction, or a file reached inside a walked directory) reports a non-regular Stat mode — typically a stored symlink or special file entry.

Common situations: Same class as the walker guard: tars with symlinks, crafted archives, filesystem-backed pseudo-archives; races where the entry changes between walk and open are also caught here.

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/8fa483fa61772be7. Report an issue: GitHub.