Anuken/Mindustry · error · ModLoadException

Java class mods are not supported on iOS.

Error message

Java class mods are not supported on iOS.

What it means

iOS does not support dynamically loading Java class mods (no runtime JVM classloading), so when a Java mod reaches the load path on iOS, loadMod throws ModLoadException. This is a hard platform limitation, not a configuration issue.

Source

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

                        mainFile = mainFile.child(str);
                    }
                }
            }

            //make sure the main class exists before loading it; if it doesn't just don't put it there
            //if the mod is explicitly marked as java, try loading it anyway
            if(
                (mainFile.exists() || meta.java) &&
                !skipModLoading() &&
                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();

View on GitHub (pinned to f695ad7e60)

Solutions

1. Use a content-only mod (JSON, no Java main class) for iOS support.
2. Inform iOS users the Java mod is unsupported on their platform.
3. Set meta so the code path is skipped where possible.

Example fix

// before: mod with classes + main class -> 'Java class mods are not supported on iOS.'
// after: ship a content-only variant (remove classes/ and meta.main) for iOS

// Gate Java-mod loading by platform.
if(ios && (mainFile.exists() || meta.java)) {
    throw new ModLoadException("Java class mods are not supported on iOS.");
}

boolean javaModOnUnsupportedPlatform(boolean ios, ModMeta meta, Fi mainFile){
    return ios && (mainFile.exists() || meta.java);
}

try {
    mods.loadMod(file);
} catch(ModLoadException e) {
    if(e.getMessage().contains("not supported on iOS")) { /* provide content-only variant */ }
    else throw e;
}

When it happens

Trigger: A mod with a Java main class (mainFile exists or meta.java) attempts to load on an iOS build.

Common situations: Cross-platform mod distributed to iOS users; mod author unaware iOS forbids Java code.

Related errors

• Type not found: ${base}
• This mod/plugin has loaded Mindustry dependencies from its o
• Two content objects defined with the same name: '{content.na
• Not implemented on this platform!
• Attribute definitions must be objects, e.g. {heat: 10}

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