HMCL-dev/HMCL · error · UnsupportedInstallationException

FABRIC_NOT_COMPATIBLE_WITH_FORGE

FABRIC_NOT_COMPATIBLE_WITH_FORGE

Error message

FABRIC_NOT_COMPATIBLE_WITH_FORGE

What it means

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).

Solutions

1. Install Quilt into a fresh vanilla instance instead of the Forge/Fabric one.
2. Remove the existing mod loader (restore vanilla main class) before installing Quilt.
3. If you need Quilt + Forge, that combination is unsupported — choose one loader or use compatible alternatives.

Example fix

// before
quiltInstallTask.execute(); // throws on Forge instance
// after
if (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, instance.getConfiguration().getMainClass())) {
    throw new UnsupportedInstallationException(FABRIC_NOT_COMPATIBLE_WITH_FORGE); // check before scheduling
}
quiltInstallTask.execute();

String mainClass = manifest.mainClass();
if (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, mainClass))
    throw new IllegalStateException("Quilt requires a vanilla instance; current main class: " + mainClass);

try {
    await(task);
} catch (UnsupportedInstallationException e) {
    if (e.getLocalizedMessage().contains("FABRIC_NOT_COMPATIBLE_WITH_FORGE")) {
        // create a fresh vanilla instance and install Quilt there
    }
}

When it happens

Trigger: 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.

Common situations: Users trying to add Quilt to an existing Forge instance, or an OptiFine-patched instance whose main class is the launch wrapper.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot fix optifine
• Fabric metadata is invalid
• File missing:
• File is not a Fabric mod.
• "File " + modFile + " is not a Forge 1.13+ or NeoForge mod."

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/quilt/QuiltInstallTask.java:65

    public QuiltInstallTask(DefaultDependencyManager dependencyManager, GameInstanceManifest manifest, QuiltRemoteVersion remoteVersion) {
        this.dependencyManager = dependencyManager;
        this.manifest = manifest;
        this.remote = remoteVersion;

        launchMetaTask = new GetTask(dependencyManager.getDownloadProvider().injectURLsWithCandidates(remoteVersion.getUrls()));
        launchMetaTask.setCacheRepository(dependencyManager.getCacheRepository());
    }

    @Override
    public boolean doPreExecute() {
        return true;
    }

    @Override
    public void preExecute() throws Exception {
        if (!Objects.equals(GameComponentAnalyzer.VANILLA_MAIN, manifest.mainClass()))
            throw new UnsupportedInstallationException(FABRIC_NOT_COMPATIBLE_WITH_FORGE);
    }

    @Override
    public Collection<Task<?>> getDependents() {
        return Collections.singleton(launchMetaTask);
    }

    @Override
    public Collection<Task<?>> getDependencies() {
        return dependencies;
    }

    @Override
    public boolean isRelyingOnDependencies() {
        return false;
    }

    @Override

View on GitHub (pinned to 24702dc5a0)