{"record":{"id":"89f66d63e1cffedc","repo":"HMCL-dev/HMCL","slug":"mismatched-game-version-requirement-library-requi","errorCode":null,"errorMessage":"Mismatched game version requirement, library requires game to be ${expect}, but actual is ${actual}","messagePattern":"Mismatched game version requirement, library requires game to be (.+?), but actual is (.+?)","errorType":"exception","errorClass":"VersionMismatchException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/optifine/OptiFineInstallTask.java","lineNumber":283,"sourceCode":"            String gameVersion,\n            Path installer) throws IOException, VersionMismatchException {\n        try (FileSystem fs = CompressingUtils.createReadOnlyZipFileSystem(installer)) {\n            Path configClass = fs.getPath(\"Config.class\");\n            if (!Files.exists(configClass)) configClass = fs.getPath(\"net/optifine/Config.class\");\n            if (!Files.exists(configClass)) configClass = fs.getPath(\"notch/net/optifine/Config.class\");\n            if (!Files.exists(configClass)) throw new IOException(\"Unrecognized installer\");\n            ConstantPool pool = ConstantPoolScanner.parse(Files.readAllBytes(configClass), ConstantType.UTF8);\n            List<String> constants = new ArrayList<>();\n            pool.list(Utf8Constant.class).forEach(utf8 -> constants.add(utf8.get()));\n            String mcVersion = getOrDefault(constants, constants.indexOf(\"MC_VERSION\") + 1, null);\n            String ofEdition = getOrDefault(constants, constants.indexOf(\"OF_EDITION\") + 1, null);\n            String ofRelease = getOrDefault(constants, constants.indexOf(\"OF_RELEASE\") + 1, null);\n\n            if (mcVersion == null || ofEdition == null || ofRelease == null)\n                throw new IOException(\"Unrecognized OptiFine installer\");\n\n            if (!mcVersion.equals(gameVersion))\n                throw new VersionMismatchException(mcVersion, gameVersion);\n\n            OptiFineRemoteVersion remoteVersion = new OptiFineRemoteVersion(\n                    mcVersion,\n                    ofEdition + \"_\" + ofRelease,\n                    Collections.singletonList(\"\"),\n                    false);\n            return new GameDownloadTask(dependencyManager, manifest)\n                    .thenComposeAsync(minecraftJar -> new OptiFineInstallTask(\n                            dependencyManager,\n                            manifest,\n                            remoteVersion,\n                            minecraftJar,\n                            installer));\n        }\n    }\n}\n","sourceCodeStart":265,"sourceCodeEnd":300,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/optifine/OptiFineInstallTask.java#L265-L300","documentation":"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.","triggerScenarios":"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.","commonSituations":"Users picking the wrong OptiFine build for their Minecraft version, or instances whose version was upgraded after OptiFine was chosen.","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."],"exampleFix":"// before\nif (!mcVersion.equals(gameVersion))\n    throw new VersionMismatchException(mcVersion, gameVersion);\n// after\nif (!mcVersion.equals(gameVersion))\n    throw new VersionMismatchException(mcVersion, gameVersion); // caller must select OptiFine_<gameVersion>_* installer","handlingStrategy":"validation","validationCode":"String gameVersion = repository.getGameVersion(instance).get(0);\nString installerMcVersion = extractMcVersion(installerFileName); // e.g. OptiFine_1.20.1_HD_U_I6.jar -> 1.20.1\nif (!installerMcVersion.equals(gameVersion))\n    throw new IllegalArgumentException(\"OptiFine \" + installerMcVersion + \" does not match game \" + gameVersion);","typeGuard":null,"tryCatchPattern":"try {\n    await(task);\n} catch (VersionMismatchException e) {\n    // e reports required vs actual version; prompt user to pick matching OptiFine build\n    log.warning(\"OptiFine targets \" + e.getExpectVersion() + \" but instance is \" + e.getActualVersion());\n}","preventionTips":["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"],"tags":["optifine","version-mismatch","installer","minecraft-version"],"backgroundTag":"version-mismatch","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}