What causes "Failed to load image {file} for mod {mod.name}" in Anuken/Mindustry?

Open the named file in an image editor to confirm it is a valid image.

Anuken/Mindustry · error · Exception

Failed to load image {file} for mod {mod.name}

Error message

Failed to load image {file} for mod {mod.name}

What it means

While loading a mod's textures, each image is decoded inside a try block; any failure (corrupt file, unsupported format, IO error) is caught and rethrown as an Exception carrying the mod name and source file so the cause is attributable.

Source

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

                    //only bleeds when linear filtering is on at startup
                    if(bleed){
                        Pixmaps.bleed(pix, 2);
                    }
                    //this returns a *runnable* which actually packs the resulting pixmap; this has to be done synchronously outside the method
                    return () -> {
                        //don't prefix with mod name if it's already prefixed by a category, e.g. `block-modname-content-full`.
                        int hyphen = baseName.indexOf('-');
                        String fullName = ((prefix && !(hyphen != -1 && baseName.substring(hyphen + 1).startsWith(mod.name + "-"))) ? mod.name + "-" : "") + baseName;

                        packer.add(getPage(file), fullName, new PixmapRegion(pix));
                        if(textureScale != 1.0f){
                            textureResize.put(fullName, textureScale);
                        }
                        pix.dispose();
                    };
                }catch(Exception e){
                    //rethrow exception with details about the cause of failure
                    throw new Exception("Failed to load image " + file + " for mod " + mod.name, e);
                }
            }));
        }
    }

    void waitForMain(Runnable run){
        CountDownLatch latch = new CountDownLatch(1);
        Core.app.post(() -> {
            run.run();
            latch.countDown();
        });
        try{
            latch.await();
        }catch(InterruptedException e){
            throw new RuntimeException(e);
        }
    }

View on GitHub (pinned to f695ad7e60)

Solutions

Open the named file in an image editor to confirm it is a valid image.
Re-export the sprite as PNG.
Check exact filename/case matches the JSON reference.
Verify the mod archive is not truncated/corrupt.

Example fix

// before: sprites/my-block.png is a JPEG renamed to .png -> load fails
// after: re-export as a true PNG

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate that a texture file is decodable before the packer touches it.
try (var in = file.read()) {
    Pixmap p = new Pixmap(new PixmapIO().read(in));
    if(p.width == 0) throw new IOException("Empty pixmap: " + file);
    p.dispose();
} catch(Exception e) {
    throw new IOException("Unreadable texture " + file, e);
}

Try / catch

try {
    // texture loading / packing
} catch(Exception e) {
    // e.getMessage() is 'Failed to load image <file> for mod <mod>'; e.getCause() is the decode error
    log.error("{}", e.getMessage(), e.getCause());
}

Prevention

Export all sprites as valid PNGs.
Match filenames exactly (case-sensitive) to JSON references.
Run an image-validation pass during the mod build.

When it happens

Trigger: A sprite file in the mod cannot be decoded/loaded — corrupt PNG, wrong format, zero-byte file, or IO read failure.

Common situations: Bad/corrupt texture export; non-PNG file with .png extension; file truncated during download; case-sensitivity mismatch on the file path.

Related errors

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