{"record":{"id":"e742472c66fb5b35","repo":"Anuken/Mindustry","slug":"failed-to-load-image-file-for-mod-mod-name","errorCode":null,"errorMessage":"Failed to load image {file} for mod {mod.name}","messagePattern":"Failed to load image (.+?) for mod (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"core/src/mindustry/mod/Mods.java","lineNumber":420,"sourceCode":"                    //only bleeds when linear filtering is on at startup\n                    if(bleed){\n                        Pixmaps.bleed(pix, 2);\n                    }\n                    //this returns a *runnable* which actually packs the resulting pixmap; this has to be done synchronously outside the method\n                    return () -> {\n                        //don't prefix with mod name if it's already prefixed by a category, e.g. `block-modname-content-full`.\n                        int hyphen = baseName.indexOf('-');\n                        String fullName = ((prefix && !(hyphen != -1 && baseName.substring(hyphen + 1).startsWith(mod.name + \"-\"))) ? mod.name + \"-\" : \"\") + baseName;\n\n                        packer.add(getPage(file), fullName, new PixmapRegion(pix));\n                        if(textureScale != 1.0f){\n                            textureResize.put(fullName, textureScale);\n                        }\n                        pix.dispose();\n                    };\n                }catch(Exception e){\n                    //rethrow exception with details about the cause of failure\n                    throw new Exception(\"Failed to load image \" + file + \" for mod \" + mod.name, e);\n                }\n            }));\n        }\n    }\n\n    void waitForMain(Runnable run){\n        CountDownLatch latch = new CountDownLatch(1);\n        Core.app.post(() -> {\n            run.run();\n            latch.countDown();\n        });\n        try{\n            latch.await();\n        }catch(InterruptedException e){\n            throw new RuntimeException(e);\n        }\n    }\n","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/Anuken/Mindustry/blob/f695ad7e60323ebced984fa26d0bcf0bc54296b4/core/src/mindustry/mod/Mods.java#L402-L438","documentation":"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.","triggerScenarios":"A sprite file in the mod cannot be decoded/loaded — corrupt PNG, wrong format, zero-byte file, or IO read failure.","commonSituations":"Bad/corrupt texture export; non-PNG file with .png extension; file truncated during download; case-sensitivity mismatch on the file path.","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."],"exampleFix":"// before: sprites/my-block.png is a JPEG renamed to .png -> load fails\n// after: re-export as a true PNG","handlingStrategy":"try-catch","validationCode":"// Pre-validate that a texture file is decodable before the packer touches it.\ntry (var in = file.read()) {\n    Pixmap p = new Pixmap(new PixmapIO().read(in));\n    if(p.width == 0) throw new IOException(\"Empty pixmap: \" + file);\n    p.dispose();\n} catch(Exception e) {\n    throw new IOException(\"Unreadable texture \" + file, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    // texture loading / packing\n} catch(Exception e) {\n    // e.getMessage() is 'Failed to load image <file> for mod <mod>'; e.getCause() is the decode error\n    log.error(\"{}\", e.getMessage(), e.getCause());\n}","preventionTips":["Export all sprites as valid PNGs.","Match filenames exactly (case-sensitive) to JSON references.","Run an image-validation pass during the mod build."],"tags":["modding","textures","io","assets"],"backgroundTag":null,"analyzedSha":"f695ad7e60323ebced984fa26d0bcf0bc54296b4","analyzedAt":"2026-08-14T04:31:16.262Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}