{"record":{"id":"4e5f7b8ddac4055d","repo":"HMCL-dev/HMCL","slug":"fabric-not-compatible-with-forge","errorCode":"FABRIC_NOT_COMPATIBLE_WITH_FORGE","errorMessage":"FABRIC_NOT_COMPATIBLE_WITH_FORGE","messagePattern":"FABRIC_NOT_COMPATIBLE_WITH_FORGE","errorType":"error_code","errorClass":"UnsupportedInstallationException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/download/quilt/QuiltInstallTask.java","lineNumber":65,"sourceCode":"\n    public QuiltInstallTask(DefaultDependencyManager dependencyManager, GameInstanceManifest manifest, QuiltRemoteVersion remoteVersion) {\n        this.dependencyManager = dependencyManager;\n        this.manifest = manifest;\n        this.remote = remoteVersion;\n\n        launchMetaTask = new GetTask(dependencyManager.getDownloadProvider().injectURLsWithCandidates(remoteVersion.getUrls()));\n        launchMetaTask.setCacheRepository(dependencyManager.getCacheRepository());\n    }\n\n    @Override\n    public boolean doPreExecute() {\n        return true;\n    }\n\n    @Override\n    public void preExecute() throws Exception {\n        if (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, manifest.mainClass()))\n            throw new UnsupportedInstallationException(FABRIC_NOT_COMPATIBLE_WITH_FORGE);\n    }\n\n    @Override\n    public Collection<Task<?>> getDependents() {\n        return Collections.singleton(launchMetaTask);\n    }\n\n    @Override\n    public Collection<Task<?>> getDependencies() {\n        return dependencies;\n    }\n\n    @Override\n    public boolean isRelyingOnDependencies() {\n        return false;\n    }\n\n    @Override","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/download/quilt/QuiltInstallTask.java#L47-L83","documentation":"Thrown in QuiltInstallTask.preExecute() when the target instance's main class is not the vanilla launch main class. Quilt (like Fabric) cannot be installed on top of an already-modded (Forge/Fabric/Quilt) instance, so installation is rejected with UnsupportedInstallationException(FABRIC_NOT_COMPATIBLE_WITH_FORGE).","triggerScenarios":"Calling preExecute() on an instance whose manifest.mainClass() differs from GameComponentAnalyzer.VANILLA_MAIN — i.e. the instance already has Forge, Fabric, OptiFine-with-launch-wrapper, or another mod loader installed.","commonSituations":"Users trying to add Quilt to an existing Forge instance, or an OptiFine-patched instance whose main class is the launch wrapper.","solutions":["Install Quilt into a fresh vanilla instance instead of the Forge/Fabric one.","Remove the existing mod loader (restore vanilla main class) before installing Quilt.","If you need Quilt + Forge, that combination is unsupported — choose one loader or use compatible alternatives."],"exampleFix":"// before\nquiltInstallTask.execute(); // throws on Forge instance\n// after\nif (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, instance.getConfiguration().getMainClass())) {\n    throw new UnsupportedInstallationException(FABRIC_NOT_COMPATIBLE_WITH_FORGE); // check before scheduling\n}\nquiltInstallTask.execute();","handlingStrategy":"validation","validationCode":"String mainClass = manifest.mainClass();\nif (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, mainClass))\n    throw new IllegalStateException(\"Quilt requires a vanilla instance; current main class: \" + mainClass);","typeGuard":null,"tryCatchPattern":"try {\n    await(task);\n} catch (UnsupportedInstallationException e) {\n    if (e.getLocalizedMessage().contains(\"FABRIC_NOT_COMPATIBLE_WITH_FORGE\")) {\n        // create a fresh vanilla instance and install Quilt there\n    }\n}","preventionTips":["Check the instance's main class before scheduling mod loader installs","Never layer Quilt on top of Forge/Fabric/OptiFine-launch-wrapper instances","Create a new instance for a different mod loader"],"tags":["quilt","fabric","forge","incompatible-mod-loader","unsupported"],"backgroundTag":"unsupported-operation","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"}