HMCL-dev/HMCL · error · IllegalStateException

Unsupported mod loader

Error message

Unsupported mod loader 

What it means

The Modrinth modpack manifest lists a dependencies key that HMCL cannot map to a supported mod loader. Only forge-loader, neoforge-loader, fabric-loader, and quilt-loader are recognized; any other key hits the default branch and aborts installation.

Solutions

1. Update HMCL to the latest version which may support the new loader
2. Edit modrinth.index.json dependencies to use a supported key (forge-loader, neoforge-loader, fabric-loader, quilt-loader)
3. Remove the unsupported dependency entry and install the loader manually after the pack installs

Example fix

// before
"dependencies": { "minecraft": "1.20.1", "fabric": "0.15.0" }
// after
"dependencies": { "minecraft": "1.20.1", "fabric-loader": "0.15.0" }

Set.of("forge-loader","neoforge-loader","fabric-loader","quilt-loader").containsAll(manifest.getDependencies().keySet())

try { task.start(); } catch (IllegalStateException e) { /* notify user to update HMCL or install loader manually */ }

When it happens

Trigger: Importing a Modrinth .mrpack whose modrinth.index.json dependencies contains an unrecognized loader key or a key added by a newer Modrinth spec version.

Common situations: New loader types introduced by Modrinth before HMCL adds support; hand-edited manifests with typos like 'forge' or 'fabric' instead of the full loader key.

Related errors

• Cannot parse the version of
• File is not a Fabric mod.
• "File " + modFile + " is not a Forge 1.13+ or NeoForge mod."
• "File " + modFile + " is not a Forge mod."
• Instance

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/modrinth/ModrinthInstallTask.java:205

                switch (modLoader.getKey()) {
                    case "minecraft":
                        break;
                    case "forge":
                        builder.component(GameComponentType.FORGE, modLoader.getValue());
                        break;
                    case "neoforge":
                    // https://github.com/HMCL-dev/HMCL/pull/5170
                    case "neo-forge":
                        builder.component(GameComponentType.NEO_FORGE, modLoader.getValue());
                        break;
                    case "fabric-loader":
                        builder.component(GameComponentType.FABRIC, modLoader.getValue());
                        break;
                    case "quilt-loader":
                        builder.component(GameComponentType.QUILT, modLoader.getValue());
                        break;
                    default:
                        throw new IllegalStateException("Unsupported mod loader " + modLoader.getKey());
                }
            }
            dependents.add(0, builder.buildAsync());
        }
    }

    @Override
    public Collection<Task<?>> getDependents() {
        return dependents;
    }

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

    @Override
    public void execute() throws Exception {

View on GitHub (pinned to 24702dc5a0)