Anuken/Mindustry · error · ModLoadException

This mod/plugin has loaded Mindustry dependencies from its o

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.

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)

Solutions

1. Declare Mindustry (and arc) as compileOnly in Gradle.
2. Build the JAR from runtimeClasspath so deps are not embedded.
3. If using ShadowJar, exclude mindustry/arc artifacts from the shadow config.
4. 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
}

// 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 {
    mods.loadMod(file);
} catch(ModLoadException e) {
    if(e.getMessage().contains("incorrectly including Mindustry dependencies")) {
        // rebuild with compileOnly + runtimeClasspath jar
    } else throw e;
}

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

• Type not found: ${base}
• Invalid file: No mod.json found.
• A mod with the name '{baseName}' is already imported.
• Java class mods are not supported on iOS.
• ----\n\nSET A BUILD NUMBER FIRST!\n\n----

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