HMCL-dev/HMCL · error · IOException

is not a valid archive file

Error message

{file} is not a valid archive file

What it means

ArchiveFileTree.open guard: the given path either has no file name (e.g. a filesystem root) or has an extension other than .jar/.zip/.tar/.tar.gz/.tgz, so no archive backend can open it. Generic sentinel error for an unsupported or invalid archive input.

Solutions

1. Pass the actual archive file path (e.g. mods/somefile.jar), not a directory or root.
2. Validate that the path points to a regular file before calling open().
3. Check upstream code that produced the Path for empty/unresolved components.
4. Catch IOException and log the path that failed classification.

Example fix

// before
ArchiveFileTree.open(Path.of("/"));
// after
Path file = Path.of("mods", "mod.jar");
if (Files.isRegularFile(file)) ArchiveFileTree.open(file);

if (file != null && Files.isRegularFile(file) && file.getFileName() != null) {
    ArchiveFileTree<?, ?> tree = ArchiveFileTree.open(file);
}

boolean isOpenableArchive(Path p) {
    return p != null && p.getFileName() != null && Files.isRegularFile(p);
}

try {
    tree = ArchiveFileTree.open(file);
} catch (IOException e) {
    // invalid archive path; log and skip
}

When it happens

Trigger: Calling ArchiveFileTree.open(Path) with a path whose getFileName() is null — e.g. Path.of("/") or a root directory path.

Common situations: Passing a directory root instead of an archive file due to a misassembled path; path constructed by resolving a blank string; API returning a root Path when a download failed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Theme-pack asset entry must be a file:
• Theme-pack asset entry must be relative:
• Theme-pack asset entry must be under assets/:
• accountID is missing
• acTL chunk length must be

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/9286e57281108226. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/util/tree/ArchiveFileTree.java:42

public static ArchiveFileTree<?, ?> open(Path file) throws IOException {
    Path namePath = file.getFileName();
    if (namePath == null) {
        throw new IOException(file + " is not a valid archive file");
    }

    String name = namePath.toString();
    if (name.endsWith(".jar") || name.endsWith(".zip")) {
        return CompressingUtils.openZipTree(file);
    } else if (name.endsWith(".tar") || name.endsWith(".tar.gz") || name.endsWith(".tgz")) {
        return TarFileTree.open(file);
    } else {
        throw new IOException(file + " is not a valid archive file");
    }
}

View on GitHub (pinned to 24702dc5a0)