HMCL-dev/HMCL · error · IllegalArgumentException

"File " + file + " is not a valid mod file."

Error message

"File " + file + " is not a valid mod file."

What it means

ModManager.addMod validates that a file has a mod-like extension/filename before copying it into the managed mod directory. If isFileNameMod(Path) returns false, the file is rejected as not a recognized mod file and an IllegalArgumentException is thrown. It signals a caller-supplied input problem, not an internal failure.

Solutions

1. Verify the file is an actual mod jar (e.g. fabric-api.jar) with a recognized mod file extension before calling addMod
2. Check for typos or missing extension in the file path; rename to a standard mod filename
3. If the file is a directory or non-mod asset, do not pass it to addMod

Example fix

// before
manager.addMod(Path.of("~/Downloads/configs.zip"));
// after
Path file = Path.of("~/Downloads/fabric-api-0.100.1.jar");
if (manager.isFileNameMod(file)) {
    manager.addMod(file);
}

if (!modManager.isFileNameMod(file)) {
    throw new IllegalArgumentException("Not a mod file: " + file);
}
modManager.addMod(file);

boolean isModFile = java.util.regex.Pattern.compile("(?i).+\\.(jar|zip|litemod)").matcher(file.getFileName().toString()).matches();

When it happens

Trigger: Calling ModManager.addMod(Path) with a file whose name does not match accepted mod file name patterns (e.g. not .jar/.litemod/.zip-style mod names, or a directory).

Common situations: Users dragging non-mod files (configs, world data, documents) into the mods import dialog; passing a mod subfolder instead of the jar; extensions in unusual case or double extensions.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• "File '" + file + "' is not a resource pack"
• Theme background opacity must be between 0 and 1:
• Unknown type of file
• accountID is missing
• Bad Implementation-Title

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/addon/mod/ModManager.java:232

    @Override
    public Comparator<LocalModFile> getComparator() {
        return LocalModFile::compareTo;
    }

    public @Unmodifiable List<LocalModFile> getLocalFiles() throws IOException {
        lock.lock();
        try {
            if (!loaded)
                refresh();
            return super.getLocalFiles();
        } finally {
            lock.unlock();
        }
    }

    public void addMod(Path file) throws IOException {
        if (!isFileNameMod(file))
            throw new IllegalArgumentException("File " + file + " is not a valid mod file.");

        lock.lock();
        try {
            if (!loaded)
                refresh();

            Path modsDirectory = getDirectory();
            Files.createDirectories(modsDirectory);

            Path newFile = modsDirectory.resolve(file.getFileName());
            FileUtils.copyFile(file, newFile);

            addModInfo(newFile);
        } finally {
            lock.unlock();
        }
    }

View on GitHub (pinned to 24702dc5a0)