HMCL-dev/HMCL · error · FileNotFoundException

Minecraft client JAR not found:

Error message

Minecraft client JAR not found: 

What it means

execute() requires the Minecraft client jar path (minecraftJar) to be a regular file before extracting data files and running processors. If it is missing, FileNotFoundException("Minecraft client JAR not found: <path>") is thrown with the path appended. Forge's processors need the vanilla client jar as input, so installation aborts.

Solutions

1. Download the vanilla client for that version first (launch vanilla once, or let HMCL install the game files), then install Forge
2. Verify versions/<minecraft-version>/<minecraft-version>.jar exists in the game repository
3. Restore the jar from recycle bin/backup or reinstall the instance
4. Check that the instance's game directory setting points to the right folder

// ensure the vanilla client jar exists before installing Forge
Path jar = gameDir.resolve("versions/" + mcVersion + "/" + mcVersion + ".jar");
if (!Files.isRegularFile(jar)) downloadVanillaClient(mcVersion);

try { installTask.execute(); } catch (FileNotFoundException e) { if (e.getMessage().startsWith("Minecraft client JAR not found")) { installVanillaFirst(mcVersion); } else throw e; }

When it happens

Trigger: ForgeNewInstallTask.execute() called when Files.isRegularFile(minecraftJar) is false — the vanilla game jar was never downloaded, was deleted, or the supplied path is wrong (e.g. jar not yet installed for that version).

Common situations: Installing Forge on a fresh instance before vanilla assets were downloaded; user manually deleted versions/<v>/<v>.jar; game directory moved/renamed; version isolated instances pointing at a non-existent jar.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Illegal pattern (Bad escape):
• Illegal pattern (Unclosed ):
• Illegal pattern: Missing Key:
• Malformed forge installer file
• client_mappings download info not found

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/forge/ForgeNewInstallTask.java:399

                    mappingsTask.setCacheRepository(dependencyManager.getCacheRepository());
                    return mappingsTask;
                });
    }

    private Task<?> createProcessorTask(Processor processor, Map<String, String> vars) {
        Task<?> task = patchDownloadMojangMappingsTask(processor, vars);
        if (task == null) {
            task = new ProcessorTask(processor, vars);
        }
        task.onDone().register(
                () -> updateProgress(processorDoneCount.incrementAndGet(), processors.size()));
        return task;
    }

    @Override
    public void execute() throws Exception {
        if (!Files.isRegularFile(minecraftJar)) {
            throw new FileNotFoundException("Minecraft client JAR not found: " + minecraftJar);
        }
        tempDir = Files.createTempDirectory("forge_installer");
        // External processors must not receive the shared cache path.
        Path isolatedMinecraftJar = tempDir.resolve("minecraft.jar");
        FileUtils.copyFile(minecraftJar, isolatedMinecraftJar);

        Map<String, String> vars = new HashMap<>();

        try (FileSystem fs = CompressingUtils.createReadOnlyZipFileSystem(installer)) {
            for (Map.Entry<String, String> entry : profile.getData().entrySet()) {
                String key = entry.getKey();
                String value = entry.getValue();

                vars.put(key, parseLiteral(value,
                        Collections.emptyMap(),
                        str -> {
                            Path dest = Files.createTempFile(tempDir, null, null);
                            FileUtils.copyFile(fs.getPath(str), dest);

View on GitHub (pinned to 24702dc5a0)