Run debugger in tests with gradle on wsl doesn't work: agent library failed Agent_OnLoad: instrument

Hi Piotr16pl 

Thanks for the report. We have a bug registered for this problem, please follow updates in the ticket IDEA-377411.

The debugger error in IntelliJ IDEA 2025.2 is a known issue caused by a **pathing mismatch** between Windows and WSL2. The IDE, running on Windows, tries to load the `debugger-agent.jar` file using a Windows-style path (`C:\Users\...`), but the test runner's VM operates in the Linux environment of WSL2, which cannot interpret that path. The solution is to create a **symbolic link** within your WSL mymilestonecard terminal that points to the location of the `.jar` file on your Windows drive, allowing the VM to access it correctly.

Ackerman254ricksar How exactly should I create the symbolic link? Where should I put it in? How to force intellij to use that link instead windows path?

Hello Ackerman254ricksar How exactly should I create the symbolic link? Where should I put it in? How to force intellij to use that link instead windows path?

Hi Mateusz ,

According to Ackerman254ricksar suggestion, here is the answer to your questions:

1. Create the symlink: use ln -s in WSL, pointing from a Linux path you control to the /mnt/c/… path of debugger-agent.jar
2. Where to put it: anywhere readable by your WSL runtime; /usr/local/share/idea-debug or /opt/idea-agent are good, stable choices.
3. How to force IntelliJ to use that link: add -javaagent:<linux-path-to-symlink>/debugger-agent.jar to the Run/Debug Configuration VM options for the app or tests.

You also can try the next three approaches:

Option A — Create a symlink inside WSL to the Windows JAR

1. Find the Windows path IntelliJ is trying to use (e.g., C:\Users<you>\AppData\Local\JetBrains\IntelliJIdea2025.2\plugins\java\lib\debugger-agent.jar).
2. In WSL, that same path is visible under /mnt/c/… For example: /mnt/c/Users//AppData/Local/JetBrains/IntelliJIdea2025.2/plugins/java/lib/debugger-agent.jar
3. Pick a stable Linux-side location to host the symlink, e.g., /usr/local/share/idea-debug
4. Create the directory and symlink:
   1. sudo mkdir -p /usr/local/share/idea-debug
   2. sudo ln -s "/mnt/c/Users//AppData/Local/JetBrains/IntelliJIdea2025.2/plugins/java/lib/debugger-agent.jar" /usr/local/share/idea-debug/debugger-agent.jar
5. Tell IntelliJ to use the Linux path:

   1. Run/Debug Configuration | VM options, add: 

      -javaagent:/usr/local/share/idea-debug/debugger-agent.jar

   2. Or if it’s a test runner using JUnit config, place the same VM option there.
6. This forces the VM to load the agent via a Linux path, avoiding the Windows path entirely.

Option B — Map the Windows directory into a WSL bind mount

1. Create a Linux mount point:

   sudo mkdir -p /opt/idea-agent

2. Bind-mount the Windows folder that contains the agent:

   sudo mount --bind "/mnt/c/Users//AppData/Local/JetBrains/IntelliJIdea2025.2/plugins/java/lib" /opt/idea-agent

3. Use VMOption

   -javaagent:/opt/idea-agent/debugger-agent.jar

4. To persist across sessions, add a line to /etc/fstab (optional):

   /mnt/c/Users//AppData/Local/JetBrains/IntelliJIdea2025.2/plugins/java/lib /opt/idea-agent none bind 0 0

Option C — Make IntelliJ launch and debug directly in WSL (no path translation needed)

1. In IntelliJ go to Settings | Build, Execution, Deployment | Toolchains | WSL, configure your WSL distribution, and set the JDK located inside WSL (e.g., /usr/lib/jvm/…).
2. Use a WSL-based JDK in Project Structure and in your Run/Debug Configurations.
3. Now the IDE uses Linux paths natively when launching the VM, eliminating Windows-style paths.

Monica sorry but I doubt your answer was generated by AI. 

I don't see there are any places to configure `Run/Debug Configuration | VM options` for Option A and B, unless you are talking about the VM options for one particular run. But I have also tried it, still doing the same thing. 

As for option C, at least for me, the reason I am getting the same error is that I am using JDK located in WSL2. 

Hi Cuichen Li94 

Thanks for the update. I apologize if I wasn't so clear, I meant Run/Debug configuration.

The problem is related to the way path is read, as soon as we find a workaround we'll share it. I keep looking at it.

Meanwhile please subscribe to the original issue for further updates from development side.

I tried option A, but same issue.

The path provided by “-javaagent” related to WSL path is not used and path Windows style “C:\…” continues to be used :(

Hi Damien Guerin 

Thanks for testing the solutions. Our developers are working hard to solve the issue as soon as possible. Please subscribe and upvote the original bug, IDEA-285542, and keep track of its progress.

If we find a workaround that fits for all scenarios in the meantime we'll add it in the ticket.