[1.21.1] JPMS ResolutionException when Gradle cache is symlinked to separate mount on Linux

[dalizi2333]

Environment

• OS: CachyOS Linux (Arch-based)
• Java: Temurin 21.0.11 / 21.0.12 (both crash), GraalVM 21.0.2 (crash)
• NeoForge: 21.1.133 (reproduced with official MDK)
• ModLauncher: 11.0.4
• moddev: 2.0.141
• Gradle: 8.11.1

Description

Running runServer on NeoForge 1.21.1 MDK crashes on Linux with:

Exception in thread "main" java.lang.module.ResolutionException: 
Module fml_loader reads more than one module named fml_earlydisplay
    at MC-BOOTSTRAP/cpw.mods.modlauncher@11.0.4/cpw.mods.modlauncher.ModuleLayerHandler.buildLayer(ModuleLayerHandler.java:75)

Root Cause

The development environment puts earlydisplay-4.0.38.jar and loader-4.0.38.jar in both:

1. -cp (classpath)
2. -DlegacyClassPath.file (legacyClasspath)

ModuleLayerHandler.buildLayer collects jars from both sources without deduplication, causing JPMS to detect duplicate modules.

Trigger Condition

Only occurs when ~/.gradle/caches/modules-2/files-2.1 is a symlink to an NTFS partition (e.g., dual-boot setup sharing Gradle cache with Windows). When the symlink is removed and cache lives on btrfs directly, the issue disappears.

Platform Comparison

Environment	Gradle cache	Result
Windows 11	On NTFS (native)	✅ Works
Linux	On NTFS (via symlink)	❌ Crashes
Linux	On btrfs (no symlink)	✅ Works
Linux	Production (Prism Launcher)	✅ Works

Reproduction

1. Clone the official MDK: git clone https://github.com/NeoForgeMDKs/MDK-1.21.1-ModDevGradle.git
2. Symlink ~/.gradle/caches/modules-2/files-2.1 to an NTFS partition
3. Run ./gradlew runServer --no-daemon
4. Observe ResolutionException

Impact

• Linux users with dual-boot setups who share Gradle cache with Windows
• Development environment only; production (Prism Launcher, server jar) works fine
• NeoForge 26.1.2 (mc2612) is NOT affected (uses different loader - FancyModLoader)

Suggested Fix

In ModuleLayerHandler.buildLayer(), deduplicate the targets list:

List<String> targets = Arrays.stream(finder)
    .map(SecureJar::name)
    .distinct()
    .toList();

Or, in the moddev Gradle plugin, avoid putting the same jars in both -cp and legacyClasspath.

[shartte]

This is more likely to be an issue in FML and will also occur when you launch from an IDE, no?

I do not think we'll remove runtime classpath entries though.

[dalizi2333]

This is more likely to be an issue in FML and will also occur when you launch from an IDE, no?

I do not think we'll remove runtime classpath entries though.

Thanks for the quick response! A few clarifications based on our testing:

1. This crash is specific to the development environment. Running the same mod on the same Linux machine via Prism Launcher (production) works fine without any JPMS issues. The crash only happens when launching via runServer in the Gradle dev environment.

2. The trigger is the Gradle cache being symlinked to an NTFS partition. This is a common setup for dual-boot users who share their Gradle cache between Windows and Linux. When the cache is on btrfs (no symlink), the issue disappears. The same Java version (Temurin 21.0.11) works on Windows with the same NTFS cache.

3. The root cause is in ModuleLayerHandler.buildLayer() (ModLauncher 11.0.4). When collecting jars from both -cp and -DlegacyClassPath.file, the targets list is not deduplicated:

List<String> targets = Arrays.stream(finder)
    .map(SecureJar::name)
    .toList();  // ← may contain duplicates like ["fml_earlydisplay", "fml_earlydisplay"]

On Linux + NTFS symlink, this causes the JPMS Resolver.checkExportSuppliers to fail with ResolutionException.

So it's not an FML issue per se — the loader works fine in production. It's the dev environment putting the same jars in two places without deduplication. Would it be possible to add a .distinct() call in ModuleLayerHandler's target collection, or is there a better place to address this?

[sciwhiz12]

I tested this with the steps above and the following:

1. Create a blank 16G image: dd if=/dev/zero of=partition.img bs=1G count=16
2. Prepare the mountpoint /mnt to be owned by your user: sudo chown <user>:<user> /mnt
3. Create a loopback device with the image: sudo losetup sudo losetup /dev/loop1 partition.img
4. Mount the loopback device to the mountpoint: sudo mount /dev/loop1 /mnt
5. Set aside any current Gradle cache: mv ~/.gradle/caches/modules-2/files-2.1 ~/.gradle/caches/modules-2/files-2.1-old
6. Create a symbolic link: ln -s /mnt ~/.gradle/caches/modules-2/files-2.1

At this point, you should be able to run the reproduction steps above and see the issue yourself.

Note that this issue seems to affect 1.21.1, but not any later versions (at least 26.1). This is likely because we did some loader changes in 1.21.2 which removed the affected components as described below.

For teardown, delete the symbolic link, move back the Gradle cache folder, unmount the loopback device and detach the image from it (losetup -d /dev/loop1).

---

This looks to be an error in general when the Gradle cache folder is symlinked to a folder that exists on a different mount, regardless of the filesystem of that mount (NTFS, ext4, etc.).

When UserdevLocator is invoked to locate the libraries to be loaded on the PLUGIN module layer, it uses DevEnvUtils.findFileSystemRootsOfFileOnClasspath to find the libraries, which pulls paths from the class loader.

This normally works fine because the paths fed to the legacy classpath and the paths from the class loader are the same are usually the same. In that case, the modules are resolved to be the same one module based off the path (the module descriptor).

However, when a symlink is involved here, the two paths differ: one is the path using the symlink down the Gradle cache folder, and the other is the canonical path that uses the folder which the symlink targets down to. (For example, /home/<user>/.gradle/caches/modules-2/files-2.1 versus /mnt/gradle (in my testing).

Thus, because the paths differ, two separate module descriptors are created, which makes the module system error out as seen above.

---

I'm not quite sure where best to fix this properly. It probably involves turning various Paths to their canonical versions using Path#toRealPath which follows symbolic links, but I'm not quite sure where the proper places to do that are. (Open for someone to look into this and make a PR.)

I can however offer a workaround: you can use bind mounts mount --bind /mnt ~/.gradle/caches/modules-2/files-2.1 (with a mkdir ~/.gradle/caches/modules-2/files-2.1 beforehand). This avoids using symbolic links, which triggers the problem above. (This can be put into one's /etc/fstab for persistence; how to do so is left as an exercise to the reader, who is presumed to be able to figure it out 😄)