Anuken/Mindustry · error · ModLoadException

This mod/plugin has loaded Mindustry dependencies from its…

Error message

This mod/plugin has loaded Mindustry dependencies from its own class loader. You are incorrectly including Mindustry dependencies in the mod JAR - make sure Mindustry is declared as `compileOnly` in Gradle, and that the JAR is created with `runtimeClasspath`!

What it means

loadMod detects when a mod's Plugin/Mod superclass was loaded by the mod's own classloader rather than the game's, proving Mindustry itself is packaged inside the mod JAR. This causes class-cast/linkage failures, so it is rejected with guidance to use compileOnly + runtimeClasspath.

Solutions

Declare Mindustry (and arc) as compileOnly in Gradle.
Build the JAR from runtimeClasspath so deps are not embedded.
If using ShadowJar, exclude mindustry/arc artifacts from the shadow config.
Verify the built jar does not contain mindustry/ packages (unzip -l | grep mindustry).

Example fix

// before
dependencies {
    implementation 'com.github.Anuken:Mindustry:VERSION'
}
jar { from { configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) } } }

// after
dependencies {
    compileOnly 'com.github.Anuken:Mindustry:VERSION'
}
tasks.named('jar') {
    from { configurations.runtimeClasspath.collect { zipTree(it) } }
    // mindustry/arc are compileOnly -> never included
}

Defensive patterns

Strategy: validation

Validate before calling

// Build-time check: assert the packaged jar does not contain Mindustry classes.
// (run in CI) e.g.
// if unzip -l build/libs/*.jar | grep -q '^.*mindustry/'; then exit 1; fi

Try / catch

try {
    mods.loadMod(file);
} catch(ModLoadException e) {
    if(e.getMessage().contains("incorrectly including Mindustry dependencies")) {
        // rebuild with compileOnly + runtimeClasspath jar
    } else throw e;
}

Prevention

Declare Mindustry/arc as compileOnly, never implementation/api.
Build the mod jar from runtimeClasspath, not a full fat/shadow jar.
In CI, assert the produced jar contains no mindustry/ or arc/ packages.

When it happens

Trigger: The mod JAR bundles Mindustry (and/or arc) classes; the superclass resolves from the mod loader instead of the game loader.

Common situations: Gradle declares Mindustry with implementation/api instead of compileOnly; a fat/shadow jar includes runtime dependencies; build uses 'application' fat packaging.

Related errors

AI-assisted analysis of Anuken/Mindustry@f695ad7e60 (2026-08-14). Data as JSON: /api/errors/31d27ea037706691. Report an issue: GitHub.

Appendix: source

Thrown at core/src/mindustry/mod/Mods.java:1175

                Core.settings.getBool("mod-" + baseName + "-enabled", true) &&
                Version.isAtLeast(meta.minGameVersion) &&
                (meta.getMinMajor() >= minJavaModGameVersion || headless || meta.legacyCompatible) &&
                !meta.isBlacklisted() &&
                !skipModCode &&
                initialize
            ){
                if(ios){
                    throw new ModLoadException("Java class mods are not supported on iOS.");
                }

                loader = platform.loadJar(sourceFile, mainLoader);
                mainLoader.addChild(loader);
                Class<?> main = Class.forName(mainClass, true, loader);

                //detect mods that incorrectly package mindustry in the jar
                if((main.getSuperclass().getName().equals("mindustry.mod.Plugin") || main.getSuperclass().getName().equals("mindustry.mod.Mod")) &&
                    main.getSuperclass().getClassLoader() != Mod.class.getClassLoader()){
                    throw new ModLoadException(
                        "This mod/plugin has loaded Mindustry dependencies from its own class loader. " +
                        "You are incorrectly including Mindustry dependencies in the mod JAR - " +
                        "make sure Mindustry is declared as `compileOnly` in Gradle, and that the JAR is created with `runtimeClasspath`!"
                    );
                }

                metas.put(main, meta);
                mainMod = (Mod)main.getDeclaredConstructor().newInstance();
            }else{
                mainMod = null;
            }

            //all plugins are hidden implicitly
            if(mainMod instanceof Plugin){
                meta.hidden = true;
            }

            //disallow putting a description after the version

View on GitHub (pinned to f695ad7e60)