Anuken/Mindustry · error · RuntimeException

Error loading mod {mod.meta.name}

Error message

Error loading mod {mod.meta.name}

What it means

Mods.contextRun executes a runnable within a mod's context and wraps any thrown Throwable in a RuntimeException prefixed with the mod's name, so failures during mod callbacks are attributed. The original exception is the cause.

Source

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

    public Seq<LoadedMod> getMods(){
        return mods;
    }

    /** Iterates through each mod with a main class. */
    public void eachClass(Cons<Mod> cons){
        orderedMods().each(p -> p.main != null, p -> contextRun(p, () -> cons.get(p.main)));
    }

    /** Iterates through each enabled mod. */
    public void eachEnabled(Cons<LoadedMod> cons){
        orderedMods().each(LoadedMod::enabled, cons);
    }

    public void contextRun(LoadedMod mod, Runnable run){
        try{
            run.run();
        }catch(Throwable t){
            throw new RuntimeException("Error loading mod " + mod.meta.name, t);
        }
    }

    /** Tries to find the config file of a mod/plugin. */
    public @Nullable ModMeta findMeta(Fi file){
        Fi metaFile = null;
        for(String name : metaFiles){
            if((metaFile = file.child(name)).exists()){
                break;
            }
        }

        if(!metaFile.exists()){
            return null;
        }

        ModMeta meta = json.fromJson(ModMeta.class, Jval.read(metaFile.readString()).toString(Jformat.plain));
        meta.cleanup();

View on GitHub (pinned to f695ad7e60)

Solutions

1. Inspect the wrapped cause (getCause()) — the real failure and its stack trace identify the mod line.
2. Fix the mod code at the indicated location.
3. If the cause is an API/version issue, align the mod with the running game version.

Example fix

// before
contextRun(mod, () -> mod.init()); // wraps: 'Error loading mod X' caused by NPE in MyMod.init:42
// fix MyMod.init line 42 to avoid the null dereference

try {
    mods.contextRun(mod, () -> mod.init());
} catch(RuntimeException wrapper) {
    Throwable cause = wrapper.getCause(); // the real exception, attributed to mod.meta.name
    log.error("Mod {} failed: {}", mod.meta.name, cause, cause);
}

When it happens

Trigger: Any exception thrown while invoking a mod's lifecycle callback (init, load, etc.) routed through contextRun.

Common situations: Mod throws NPE/IllegalState during init; mod code incompatible with current game API; missing dependency at runtime.

Related errors

• Mod is not loaded yet (or missing)!
• Calling getPixmap outside of createIcons is not supported!
• No constructor set up for unit '{name}', add this argument t
• Two content objects defined with the same name: '{content.na
• Attribute definitions must be objects, e.g. {heat: 10}

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