{"record":{"id":"9286e57281108226","repo":"HMCL-dev/HMCL","slug":"file-is-not-a-valid-archive-file","errorCode":null,"errorMessage":"{file} is not a valid archive file","messagePattern":"(.+?) is not a valid archive file","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/util/tree/ArchiveFileTree.java","lineNumber":42,"sourceCode":"public static ArchiveFileTree<?, ?> open(Path file) throws IOException {\n    Path namePath = file.getFileName();\n    if (namePath == null) {\n        throw new IOException(file + \" is not a valid archive file\");\n    }\n\n    String name = namePath.toString();\n    if (name.endsWith(\".jar\") || name.endsWith(\".zip\")) {\n        return CompressingUtils.openZipTree(file);\n    } else if (name.endsWith(\".tar\") || name.endsWith(\".tar.gz\") || name.endsWith(\".tgz\")) {\n        return TarFileTree.open(file);\n    } else {\n        throw new IOException(file + \" is not a valid archive file\");\n    }\n}","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/util/tree/ArchiveFileTree.java#L24-L60","documentation":"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.","triggerScenarios":"Calling ArchiveFileTree.open(Path) with a path whose getFileName() is null — e.g. Path.of(\"/\") or a root directory path.","commonSituations":"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.","solutions":["Pass the actual archive file path (e.g. mods/somefile.jar), not a directory or root.","Validate that the path points to a regular file before calling open().","Check upstream code that produced the Path for empty/unresolved components.","Catch IOException and log the path that failed classification."],"exampleFix":"// before\nArchiveFileTree.open(Path.of(\"/\"));\n// after\nPath file = Path.of(\"mods\", \"mod.jar\");\nif (Files.isRegularFile(file)) ArchiveFileTree.open(file);","handlingStrategy":"validation","validationCode":"if (file != null && Files.isRegularFile(file) && file.getFileName() != null) {\n    ArchiveFileTree<?, ?> tree = ArchiveFileTree.open(file);\n}","typeGuard":"boolean isOpenableArchive(Path p) {\n    return p != null && p.getFileName() != null && Files.isRegularFile(p);\n}","tryCatchPattern":"try {\n    tree = ArchiveFileTree.open(file);\n} catch (IOException e) {\n    // invalid archive path; log and skip\n}","preventionTips":["Always pass a concrete regular-file path, never a directory root.","Validate with Files.isRegularFile before opening.","Check upstream path construction for empty components."],"tags":["archive","path","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}