HMCL-dev/HMCL · error · PatchException

Failed to download dependencies

Error message

Failed to download dependencies

What it means

During JavaFX dependency patching, HMCL checks which JavaFX artifacts are missing and downloads them. If fetchDependencies fails due to an I/O error (network failure, bad mirror, disk error), the patch() method wraps it in this PatchException and patching fails.

Solutions

1. Check network connectivity / firewall access to the Maven repository hosting OpenJFX
2. Set -Dhmcl.openjfx.repo=<mirror-url> to a reachable mirror (e.g. a Chinese mirror if default repo is blocked)
3. Configure JVM proxy settings (-Dhttps.proxyHost/-Dhttps.proxyPort) for corporate networks
4. Use a JDK with bundled JavaFX so no download is needed; free disk space and retry

Example fix

// before
java -jar HMCL.jar  # tries default repo, fails offline
// after
java -Dhmcl.openjfx.repo=https://mirrors.example.com/openjfx -jar HMCL.jar

// pre-check reachability of the OpenJFX repo
HttpURLConnection c = (HttpURLConnection) new URL(repoUrl).openConnection();
c.setConnectTimeout(5000);
if (c.getResponseCode() != 200) {
    LOG.warning("JavaFX repo unreachable; configure -Dhmcl.openjfx.repo");
}

try {
    SelfDependencyPatcher.patchIfNeeded();
} catch (PatchException e) {
    if (e.getMessage().contains("download")) {
        LOG.warning("Dependency download failed (network/mirror?). Configure hmcl.openjfx.repo or check connectivity", e);
    }
}

When it happens

Trigger: SelfDependencyPatcher.patch() is called, checkMissingDependencies() returns a non-empty list, and patcher.fetchDependencies(missingDependencies) throws IOException — network outage, unreachable repository, or local disk failure.

Common situations: No internet or firewall blocking the OpenJFX Maven repo; misconfigured hmcl.openjfx.repo system property pointing at an invalid URL; proxy requirements on corporate networks; disk full in the cache directory.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to download texture
• Failed to download theme background: HTTP
• No download url is available
• Minecraft client JAR was not downloaded
• Unexpected file size

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/util/SelfDependencyPatcher.java:182

        // Do nothing if JavaFX is detected
        try {
            Class.forName("javafx.application.Application");
            return;
        } catch (Exception ignored) {
        }

        SelfDependencyPatcher patcher = new SelfDependencyPatcher();

        // Otherwise we're free to download in Java 11+
        LOG.info("Missing JavaFX dependencies, attempting to patch in missing classes");

        // Download missing dependencies
        List<DependencyDescriptor> missingDependencies = patcher.checkMissingDependencies();
        if (!missingDependencies.isEmpty()) {
            try {
                patcher.fetchDependencies(missingDependencies);
            } catch (IOException e) {
                throw new PatchException("Failed to download dependencies", e);
            }
        }

        // Add the dependencies
        try {
            patcher.loadFromCache();
        } catch (IOException ex) {
            throw new PatchException("Failed to load JavaFX cache", ex);
        } catch (ReflectiveOperationException | NoClassDefFoundError ex) {
            throw new PatchException("Failed to add dependencies to classpath!", ex);
        }
        LOG.info(" - Done!");
    }

    private Repository showChooseRepositoryDialog() {
        final JPanel panel = new JPanel();
        panel.setLayout(new BoxLayout(panel, BoxLayout.Y_AXIS));

View on GitHub (pinned to 24702dc5a0)