AlistGo/alist · error · UnknownArchiveFormat

unknown archive format

Error message

unknown archive format

What it means

UnknownArchiveFormat is returned by the archive/decompression subsystem when it cannot detect the archive type of a file. AList inspects the file content (via stream peeking) to choose a decompress driver; if no registered format matches, this sentinel from internal/errs/errors.go is thrown.

Source

Thrown at internal/errs/errors.go:23

	"fmt"

	pkgerr "github.com/pkg/errors"
)

var (
	NotImplement = errors.New("not implement")
	NotSupport   = errors.New("not support")
	RelativePath = errors.New("access using relative path is not allowed")

	MoveBetweenTwoStorages = errors.New("can't move files between two storages, try to copy")
	UploadNotSupported     = errors.New("upload not supported")

	MetaNotFound     = errors.New("meta not found")
	StorageNotFound  = errors.New("storage not found")
	StreamIncomplete = errors.New("upload/download stream incomplete, possible network issue")
	StreamPeekFail   = errors.New("StreamPeekFail")

	UnknownArchiveFormat      = errors.New("unknown archive format")
	WrongArchivePassword      = errors.New("wrong archive password")
	DriverExtractNotSupported = errors.New("driver extraction not supported")
)

// NewErr wrap constant error with an extra message
// use errors.Is(err1, StorageNotFound) to check if err belongs to any internal error
func NewErr(err error, format string, a ...any) error {
	return fmt.Errorf("%w; %s", err, fmt.Sprintf(format, a...))
}

func IsNotFoundError(err error) bool {
	return errors.Is(pkgerr.Cause(err), ObjectNotFound) || errors.Is(pkgerr.Cause(err), StorageNotFound)
}

func IsNotSupportError(err error) bool {
	return errors.Is(pkgerr.Cause(err), NotSupport)
}
func IsNotImplement(err error) bool {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Verify the file is a genuine, complete archive (test locally with unzip/tar/7z)
2. Re-download or repair the archive if truncated
3. Confirm the format is one AList's decompression drivers support (zip, tar variants, rar, 7z per compiled-in drivers)
4. Rename the file to its true extension so detection hints match the content

// sniff magic bytes before invoking archive APIs
head := make([]byte, 8)
if r, ok := src.(io.Reader); ok {
    if _, err := io.ReadFull(r, head); err == nil {
        switch {
        case bytes.HasPrefix(head, []byte("PK\x03\x04")): // zip
        case bytes.HasPrefix(head, []byte("7z\xbc\xaf'\x1c")): // 7z
        case bytes.HasPrefix(head, []byte("Rar!")): // rar
        default: return errs.UnknownArchiveFormat
        }
    }
}

func isUnknownArchiveFormat(err error) bool {
    return err != nil && errors.Is(errors.Cause(err), errs.UnknownArchiveFormat)
}

err := extract(ctx, src, dst)
if isUnknownArchiveFormat(err) {
    // tell the user the file is not a supported/valid archive; do not retry
}

When it happens

Trigger: Calling the archive decompression API (/api/fs/archive or internal/fs/archive.go flows) on a file whose content is not a recognizable archive: a plain file, a corrupted archive, a wrong extension, or a format the bundled decompressor does not support.

Common situations: Renaming a non-archive to .zip/.tar; partially downloaded archives; proprietary or exotic compression formats; empty 0-byte files; self-extracting installers with prepended bytes that defeat content sniffing.

Related errors

• wrong archive password
• ErrArchiveIllegalPath
• paths is required
• same-name files cannot be decompressed
• same-name dirs cannot be decompressed to

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