HMCL-dev/HMCL · error · IOException

Not a valid MultiMC modpack

Error message

Not a valid MultiMC modpack

What it means

When extracting the modpack archive, HMCL looks for instance.cfg at the zip root or one directory deep. If no such entry can be found anywhere in those positions, the archive is not recognized as a MultiMC modpack and the task fails.

Solutions

1. Re-zip the modpack so instance.cfg sits at the archive root or exactly one folder deep.
2. Verify the pack is actually a MultiMC/Prism instance export (contains mmc-pack.json and instance.cfg).
3. Extract the archive, navigate to the folder that directly contains instance.cfg, and zip that folder's contents.

Example fix

// before (zip layout)
/MyPack/instances/MyInstance/instance.cfg   -> too deep
// after
/MyPack/instance.cfg                        -> one level deep, accepted

try (FileSystem fs = CompressingUtils.readonly(zip).build()) {
    boolean ok = Files.exists(fs.getPath("/instance.cfg"));
    // or scan one level of directories for instance.cfg
}

try { task.run(); } catch (IOException e) { if (e.getMessage().equals("Not a valid MultiMC modpack")) { /* prompt re-zip / wrong format */ } }

When it happens

Trigger: getRootPath(fs) called from preExecute/root: neither fs root nor any first-level directory contains instance.cfg.

Common situations: The zip contains the instance nested more than one level deep (e.g. zip-of-a-folder-containing-folder); the user zipped the wrong directory; the archive is a CurseForge/Modrinth pack mislabeled as MultiMC.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Not a valid MultiMC modpack
• /assets/
• Cannot load modpacks without Minecraft.
• Curse Forge modpack manifest Mod loader id cannot be blank.
• CurseForge Manifest.gameVersion cannot be blank.

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/multimc/MultiMCModpackInstallTask.java:491

        return Files.exists(root.resolve("instance.cfg"));
    }

    private static Path getRootPath(FileSystem fs) throws IOException {
        Path root = fs.getPath("/");

        if (testPath(root)) {
            return root;
        }

        try (DirectoryStream<Path> stream = Files.newDirectoryStream(root)) {
            for (Path candidate : stream) {
                if (testPath(candidate)) {
                    return candidate;
                }
            }
        }

        throw new IOException("Not a valid MultiMC modpack");
    }
}

View on GitHub (pinned to 24702dc5a0)