HMCL-dev/HMCL · error · VersionMismatchException

Mismatched game version requirement, library requires game…

Error message

Mismatched game version requirement, library requires game to be ${expect}, but actual is ${actual}

What it means

A VersionMismatchException raised when the OptiFine installer's MC_VERSION constant does not equal the gameVersion the user is installing into. The installer targets a different Minecraft version than the target instance.

Solutions

Download the OptiFine installer whose MC_VERSION matches the instance's game version.
Verify the instance's game version and the installer filename prefix agree (OptiFine_<mcVersion>_...).
Create a separate instance for the other Minecraft version instead of forcing the mismatch.

Example fix

// before
if (!mcVersion.equals(gameVersion))
    throw new VersionMismatchException(mcVersion, gameVersion);
// after
if (!mcVersion.equals(gameVersion))
    throw new VersionMismatchException(mcVersion, gameVersion); // caller must select OptiFine_<gameVersion>_* installer

Defensive patterns

Strategy: validation

Validate before calling

String gameVersion = repository.getGameVersion(instance).get(0);
String installerMcVersion = extractMcVersion(installerFileName); // e.g. OptiFine_1.20.1_HD_U_I6.jar -> 1.20.1
if (!installerMcVersion.equals(gameVersion))
    throw new IllegalArgumentException("OptiFine " + installerMcVersion + " does not match game " + gameVersion);

Try / catch

try {
    await(task);
} catch (VersionMismatchException e) {
    // e reports required vs actual version; prompt user to pick matching OptiFine build
    log.warning("OptiFine targets " + e.getExpectVersion() + " but instance is " + e.getActualVersion());
}

Prevention

Match the OptiFine filename prefix (OptiFine_<mcVersion>_...) to the instance version
Re-check instance version after upgrades before adding OptiFine
Keep separate instances per Minecraft version

When it happens

Trigger: install(installer, gameVersion, ...) finds mcVersion from the installer's constant pool and mcVersion.equals(gameVersion) is false — e.g. installing OptiFine_1.19.2 installer into a 1.19.4 instance.

Common situations: Users picking the wrong OptiFine build for their Minecraft version, or instances whose version was upgraded after OptiFine was chosen.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/optifine/OptiFineInstallTask.java:283

            String gameVersion,
            Path installer) throws IOException, VersionMismatchException {
        try (FileSystem fs = CompressingUtils.createReadOnlyZipFileSystem(installer)) {
            Path configClass = fs.getPath("Config.class");
            if (!Files.exists(configClass)) configClass = fs.getPath("net/optifine/Config.class");
            if (!Files.exists(configClass)) configClass = fs.getPath("notch/net/optifine/Config.class");
            if (!Files.exists(configClass)) throw new IOException("Unrecognized installer");
            ConstantPool pool = ConstantPoolScanner.parse(Files.readAllBytes(configClass), ConstantType.UTF8);
            List<String> constants = new ArrayList<>();
            pool.list(Utf8Constant.class).forEach(utf8 -> constants.add(utf8.get()));
            String mcVersion = getOrDefault(constants, constants.indexOf("MC_VERSION") + 1, null);
            String ofEdition = getOrDefault(constants, constants.indexOf("OF_EDITION") + 1, null);
            String ofRelease = getOrDefault(constants, constants.indexOf("OF_RELEASE") + 1, null);

            if (mcVersion == null || ofEdition == null || ofRelease == null)
                throw new IOException("Unrecognized OptiFine installer");

            if (!mcVersion.equals(gameVersion))
                throw new VersionMismatchException(mcVersion, gameVersion);

            OptiFineRemoteVersion remoteVersion = new OptiFineRemoteVersion(
                    mcVersion,
                    ofEdition + "_" + ofRelease,
                    Collections.singletonList(""),
                    false);
            return new GameDownloadTask(dependencyManager, manifest)
                    .thenComposeAsync(minecraftJar -> new OptiFineInstallTask(
                            dependencyManager,
                            manifest,
                            remoteVersion,
                            minecraftJar,
                            installer));
        }
    }
}

View on GitHub (pinned to 24702dc5a0)