HMCL-dev/HMCL · error · Exception

Game processor dependency missing

Error message

Game processor dependency missing

What it means

Thrown when a JAR listed in the processor's classpath is not a regular file in the game repository. Forge processors run with a classpath of several libraries; if any one is missing, HMCL aborts before launching the processor since the processor would fail anyway.

Solutions

  1. Re-run the Forge installation so GameLibrariesTask re-downloads all processor classpath libraries
  2. Identify the missing library from logs/paths and restore or download it into the libraries directory
  3. Ensure the game repository base directory is the same one used when the libraries were downloaded
  4. Clear partial downloads and retry on a stable network connection

Example fix

// before: skipping the libraries download step
processorTask.run();
// after: run the full ForgeNewInstallTask whose dependents fetch libraries first
new ForgeNewInstallTask(dependencyManager, manifest, minecraftJar, version, installer).run();
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check every classpath artifact resolves
for (Artifact a : processor.getClasspath()) {
    Path f = gameRepository.getLayout().getArtifactFile(a);
    if (!Files.isRegularFile(f)) throw new IOException("Missing library before install: " + f);
}

Try / catch

try {
    installTask.run();
} catch (Exception e) {
    if ("Game processor dependency missing".equals(e.getMessage())) {
        // re-run GameLibrariesTask / dependency downloads, then retry install
    }
}

Prevention

When it happens

Trigger: During ProcessorTask.execute(), any Artifact in processor.getClasspath() resolves via gameRepository.getLayout().getArtifactFile() to a nonexistent or non-regular path — i.e. the preprocess library download did not fetch that library.

Common situations: Incomplete libraries directory after an interrupted install; manually deleted libraries to 'clean up' disk; repository relocation; a library that failed SHA checks and was removed.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

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

                throw new FileNotFoundException("Game processor file not found, should be downloaded in preprocess");

            String mainClass;
            try (JarFile jarFile = new JarFile(jar.toFile())) {
                mainClass = jarFile.getManifest().getMainAttributes().getValue(Attributes.Name.MAIN_CLASS);
            }

            if (StringUtils.isBlank(mainClass))
                throw new Exception("Game processor jar does not have main class " + jar);

            List<String> command = new ArrayList<>();
            command.add(JavaRuntime.getDefault().getBinary().toString());
            command.add("-cp");

            List<String> classpath = new ArrayList<>(processor.getClasspath().size() + 1);
            for (Artifact artifact : processor.getClasspath()) {
                Path file = gameRepository.getLayout().getArtifactFile(artifact);
                if (!Files.isRegularFile(file))
                    throw new Exception("Game processor dependency missing");
                classpath.add(file.toString());
            }
            classpath.add(jar.toString());
            command.add(String.join(File.pathSeparator, classpath));

            command.add(mainClass);

            List<String> args = new ArrayList<>(processor.getArgs().size());
            for (String arg : processor.getArgs()) {
                String parsed = parseLiteral(arg, vars);
                if (parsed == null)
                    throw new ArtifactMalformedException("Invalid forge installation configuration");
                args.add(parsed);
            }

            command.addAll(args);

            LOG.info("Executing external processor " + processor.getJar().toString() + ", command line: " + new CommandBuilder().addAll(command).toString());

View on GitHub (pinned to 24702dc5a0)