HMCL-dev/HMCL · error · IOException

`instance.cfg` not found,

Error message

`instance.cfg` not found,

What it means

After locating the modpack root entry, readManifest requires an instance.cfg entry inside that root; instance.cfg holds the MultiMC instance configuration HMCL needs to build the Modpack metadata. Its absence means the archive looks like a MultiMC pack but is incomplete.

Solutions

  1. Add a valid instance.cfg to the instance folder inside the zip (copy one from a working MultiMC instance and edit name/version).
  2. Re-export the modpack from MultiMC/Prism Launcher so instance.cfg is included.
  3. Report the pack as broken to its maintainer and use a complete archive.

Example fix

// before (zip)
/modpack/mmc-pack.json           (instance.cfg missing)
// after
/modpack/mmc-pack.json
/modpack/instance.cfg            (required)
Defensive patterns

Strategy: validation

Validate before calling

try (ZipArchiveReader r = new ZipArchiveReader(zip)) {
    boolean ok = r.getEntry("instance.cfg") != null
        || r.getEntry(rootDir + "/instance.cfg") != null;
}

Try / catch

try { Modpack m = provider.readManifest(reader, zipPath, encoding); } catch (IOException e) { if (e.getMessage().contains("instance.cfg` not found")) { /* reject/repair the pack */ } }

Prevention

When it happens

Trigger: MultiMCModpackProvider.readManifest: rootEntryName was resolved from mmc-pack.json, but modpackFile.getEntry(rootEntryName + "instance.cfg") returns null.

Common situations: A partially exported or hand-trimmed MultiMC instance where instance.cfg was deleted; a zip that has mmc-pack.json but lost instance.cfg; mixed archives assembled manually.

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

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/multimc/MultiMCModpackProvider.java:86

            if (idx >= 0
                    && entryName.length() == idx + instanceFileName.length() + 1
                    && entryName.startsWith(instanceFileName, idx + 1))
                return entryName.substring(0, idx + 1);
        }

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

    @Override
    public Modpack readManifest(ZipArchiveReader modpackFile, Path modpackPath, Charset encoding) throws IOException {
        String rootEntryName = getRootEntryName(modpackFile);
        MultiMCManifest manifest = MultiMCManifest.readMultiMCModpackManifest(modpackFile, rootEntryName);

        String name = rootEntryName.isEmpty() ? FileUtils.getNameWithoutExtension(modpackPath) : rootEntryName.substring(0, rootEntryName.length() - 1);
        ZipArchiveEntry instanceEntry = modpackFile.getEntry(rootEntryName + "instance.cfg");

        if (instanceEntry == null)
            throw new IOException("`instance.cfg` not found, " + modpackFile + " is not a valid MultiMC modpack.");
        try (InputStream instanceStream = modpackFile.getInputStream(instanceEntry)) {
            MultiMCInstanceConfiguration cfg = new MultiMCInstanceConfiguration(name, instanceStream, manifest);
            return new Modpack(cfg.getName(), "", "", cfg.getGameVersion(), cfg.getNotes(), encoding, cfg) {
                @Override
                public Task<?> getInstallTask(DefaultDependencyManager dependencyManager, Path zipFile, GameInstanceID instanceId, String iconUrl) {
                    return new MultiMCModpackInstallTask(dependencyManager, zipFile, this, cfg, instanceId);
                }
            };
        }
    }

}

View on GitHub (pinned to 24702dc5a0)