HMCL-dev/HMCL · error · UnsupportedPlatformException

Unsupported platform

Error message

Unsupported platform: ${platform}

What it means

When HMCL downloads a Mojang-hosted Java runtime, it fetches the java-runtime JSON index and looks up the entry for the current platform (`platform`) and the requested Java component. If that OS key or the requested Java component is missing from Mojang's download index, Mojang simply doesn't ship that runtime for this OS, and MojangJavaDownloadTask throws UnsupportedPlatformException.

Solutions

1. Check your OS/architecture is one Mojang publishes runtimes for; otherwise use a different Java download source (adoptium/aliyun download provider) instead of Mojang.
2. Pick a different Java version/component that exists for your platform.
3. Correct the platform detection value passed to MojangJavaDownloadTask if it is wrong.
4. Update HMCL — platform mapping tables are fixed in newer releases.

Example fix

// before
new MojangJavaDownloadTask(downloadProvider, javaVersion, "linux-musl");
// after
new MojangJavaDownloadTask(downloadProvider, javaVersion, System.OS.toString()); // only if supported, else use Adoptium provider

// Pre-check Mojang's index for your platform before constructing the task
MojangJavaDownloads d = JsonUtils.fromNonNullJson(indexJson, MojangJavaDownloads.class);
boolean supported = d.downloads().containsKey(platform) && d.downloads().get(platform).stream().anyMatch(x -> x.component().equals(javaVersion.component()));

if (!allDownloads.downloads().containsKey(platform)) { switchToFallbackProvider(); }

try { return taskExecutor.submitTask(new MojangJavaDownloadTask(...)).get(); }
catch (UnsupportedPlatformException e) { LOG.warning(e.getMessage()); return provisionJavaViaAdoptium(javaVersion); }

When it happens

Trigger: Calling MojangJavaDownloadTask with a platform whose key is absent from MojangJavaDownloads.downloads() (e.g. an OS/architecture Mojang doesn't host), or requesting a javaVersion component (e.g. java-runtime-gamma) not published for that platform.

Common situations: Running HMCL on an uncommon OS/architecture combination (e.g. unusual Linux libc, BSD, 32-bit) where Mojang publishes no runtime; Mojang removed a runtime component for a platform; custom platform string detection returning an unsupported value.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Candidates
• Failed to download texture
• Incompatible platform: " + javaRuntime.getPlatform()
• Expecting file in terracotta bundle.
• Failed to download theme background: HTTP

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/download/java/mojang/MojangJavaDownloadTask.java:68

    private final DownloadProvider downloadProvider;
    private final Path target;
    private final Path tempDir;
    private final Task<MojangJavaRemoteFiles> javaDownloadsTask;
    private final List<Task<?>> dependencies = new ArrayList<>();

    private volatile MojangJavaDownloads.JavaDownload download;

    public MojangJavaDownloadTask(DownloadProvider downloadProvider, Path target, Path tempDir, GameJavaVersion javaVersion, String platform) {
        this.target = target;
        this.tempDir = tempDir;
        this.downloadProvider = downloadProvider;
        this.javaDownloadsTask = new GetTask(downloadProvider.injectURLWithCandidates(JAVA_LIST_URL))
                .thenComposeAsync(javaDownloadsJson -> {
                    MojangJavaDownloads allDownloads = JsonUtils.fromNonNullJson(javaDownloadsJson, MojangJavaDownloads.class);

                    Map<String, List<MojangJavaDownloads.JavaDownload>> osDownloads = allDownloads.downloads().get(platform);
                    if (osDownloads == null || !osDownloads.containsKey(javaVersion.component()))
                        throw new UnsupportedPlatformException("Unsupported platform: " + platform);
                    List<MojangJavaDownloads.JavaDownload> candidates = osDownloads.get(javaVersion.component());
                    for (MojangJavaDownloads.JavaDownload download : candidates) {
                        if (JavaInfo.parseVersion(download.version().name()) >= javaVersion.majorVersion()) {
                            this.download = download;
                            return new GetTask(downloadProvider.injectURLWithCandidates(download.manifest().getUrl()));
                        }
                    }
                    throw new UnsupportedPlatformException("Candidates: " + JsonUtils.GSON.toJson(candidates));
                })
                .thenApplyAsync(javaDownloadJson -> JsonUtils.fromNonNullJson(javaDownloadJson, MojangJavaRemoteFiles.class));
    }

    @Override
    public Collection<Task<?>> getDependents() {
        return Collections.singleton(javaDownloadsTask);
    }

    @Override

View on GitHub (pinned to 24702dc5a0)