HMCL-dev/HMCL · error · Exception

Game processor dependency missing

Error message

Game processor dependency missing

What it means

Thrown when one of the processor's declared classpath dependencies (processor.getClasspath() Artifacts) is not a regular file in the game repository. All dependencies must be pre-downloaded during preprocess; a missing one means the processor cannot be launched.

Solutions

  1. Re-run the installation so GameLibrariesTask re-downloads the missing dependency libraries
  2. Check disk space and permissions in the .minecraft/libraries directory
  3. Check the HMCL log for the earlier download failure of that artifact and fix its root cause (network/mirror)
  4. Delete the partially downloaded/corrupt file so the retry fetches a fresh copy
Defensive patterns

Strategy: validation

Validate before calling

for (Artifact a : processor.getClasspath()) {
    if (!Files.isRegularFile(gameRepository.getLayout().getArtifactFile(a))) reDownloadLibraries();
}

Try / catch

try { task.run(); } catch (Exception e) { if ("Game processor dependency missing".equals(e.getMessage())) reDownloadLibrariesAndRetry(); else throw e; }

Prevention

When it happens

Trigger: Iterating processor.getClasspath() in ProcessorTask.execute, gameRepository.getLayout().getArtifactFile(artifact) returns a path that is not a regular file — the dependency library was never downloaded, was interrupted mid-download, or was deleted.

Common situations: Incomplete library downloads (network failure, disk full, antivirus removal); interrupted previous install attempt; user cleaning libraries folder; mirror missing an artifact.

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/b261e825545f06a6. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/neoforge/NeoForgeOldInstallTask.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)