HMCL-dev/HMCL · error · IOException

"File " + modFile + " is not a LiteLoader mod."

Error message

"File " + modFile + " is not a LiteLoader mod."

What it means

LiteModMetadata.fromFile requires the archive to contain a `litemod.json` entry at its root, which is the marker of a LiteLoader mod. If absent, an IOException declares the file is not a LiteLoader mod.

Solutions

1. Confirm the file is actually a LiteLoader mod (contains `litemod.json`)
2. Only call fromFile after checking tree.getEntry("litemod.json") != null
3. Try parsing with the metadata parser matching the file's actual mod loader

Example fix

// before
LiteModMetadata.fromFile(modManager, modFile, tree);
// after
if (tree.getEntry("litemod.json") != null) {
    LiteModMetadata.fromFile(modManager, modFile, tree);
}

if (tree.getEntry("litemod.json") == null) {
    // not a LiteLoader mod; dispatch to another parser
}

boolean isLiteLoaderMod(ZipFileTree tree) {
    return tree.getEntry("litemod.json") != null;
}

try {
    LiteModMetadata.fromFile(modManager, modFile, tree);
} catch (IOException e) {
    if (e.getMessage().contains("is not a LiteLoader mod")) tryOtherParser(modFile, tree);
}

When it happens

Trigger: Calling LiteModMetadata.fromFile with a ZipFileTree for a jar that has no `litemod.json` entry (plain Forge/Fabric mod or non-mod file).

Common situations: Scanning a mixed mods folder where files of other loaders are probed for LiteLoader metadata; misnamed `.litemod` files that are really jars of another type.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• "Mod " + modFile + " `mcmod.info` is malformed"
• "Mod " + modFile + " `litemod.json` is malformed."
• "File " + modFile + " is not a Quilt mod."
• Too many attempts
• Failed to close session lock channel of the world

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/db52c67ef6c32b82. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/LiteModMetadata.java:116

        return modpackName;
    }

    public String getModpackVersion() {
        return modpackVersion;
    }

    public String getCheckUpdateUrl() {
        return checkUpdateUrl;
    }

    public String getUpdateURI() {
        return updateURI;
    }

    public static LocalModFile fromFile(ModManager modManager, Path modFile, ZipFileTree tree) throws IOException, JsonParseException {
        ZipArchiveEntry entry = tree.getEntry("litemod.json");
        if (entry == null)
            throw new IOException("File " + modFile + " is not a LiteLoader mod.");
        LiteModMetadata metadata = JsonUtils.fromJsonFully(tree.getInputStream(entry), LiteModMetadata.class);
        if (metadata == null)
            throw new IOException("Mod " + modFile + " `litemod.json` is malformed.");
        return new LocalModFile(modManager, modManager.getLocalMod(metadata.getName(), ModLoaderType.LITE_LOADER), modFile, metadata.getName(), new LocalAddonFile.Description(metadata.getDescription()), metadata.getAuthor(),
                metadata.getVersion(), metadata.getGameVersion(), metadata.getUpdateURI(), "");
    }

}

View on GitHub (pinned to 24702dc5a0)