Known Problems and Limitations
| Problem/Limitation | Workaround |
|---|---|
| Multi-module projects are not explicitly supported. The following link is for one known issue, but other undiscovered problems might exist: #555 |
You can try to work with multi-module projects, but there is no guaranteed support. Please open any newly discovered issues here: https://github.com/OpenLiberty/liberty-tools-intellij/issues. One helpful workaround to run a multi-module project with some support is to use the Liberty Start... action and specify the following parameters: |
| Depending on where dev mode is in its process of starting up, you might have trouble stopping dev mode by using the Liberty Stop action. | Click in the terminal instance in IntelliJ where dev mode is running and type ctrl + c. This should end the dev mode instance. |
| You might observe slow performance when editing your server.xml file when invoking completion or hover. It is possible you may receive a "No documentation found" message on hover. If observed, please report your experience on this GitHub issue: #687. | No workaround available. |
rest_get and mpirc completion options may appear when you trigger completion (ctrl/cmd + space) in a Java file outside of a class, where they are not applicable. |
You can ignore these suggestions when the cursor is not inside a class. |
| Diagnostics or quick fixes for Jakarta EE or MicroProfile might not be published when a file is opened and diagnostics or quick fixes should be provided. If observed, please report your experience on this GitHub issue: #648 | You can try editing the file to see if diagnostics and quick fixes appear. You can also try closing and reopening the file. |
| Problem/Limitation | Workaround |
|---|---|
While running the Liberty Start action in IntelliJ IDEA 2024.3.x and 2024.2.x , you may see the exception java.lang.Throwable: Failed to set TerminalEngine to CLASSIC via reflection: org.jetbrains.plugins.terminal.TerminalEngine. |
You can safely ignore this exception and continue using Liberty Tools normally. |
| Problem/Limitation | Workaround |
|---|---|
|
If you are using a fresh installation of IntelliJ IDEA versions 2025.1.2, 2025.1.3, or 2025.1.4.1 you may encounter a NullPointerException when trying to start Liberty Tools or open a terminal-related feature. This issue does not occur if:
JetBrains introduced a partial rollout of a new terminal engine in the IntelliJ 2025.1.x stream, which has an incompatibility with the ShellTerminalWidget API used by Liberty Tools. For more information, refer to: https://youtrack.jetbrains.com/issue/IJSDK-2593/Breaking-change-from-IntelliJ-2025.1.2-causes-NPE-in-plugin-due-to-ShellTerminalWidget-casting#focus=Comments-27-12383765.0-0. |
To resolve the issue, manually switch to the classic terminal engine:
Liberty Tools will now function without issues. Notes:
|
| Problem/Limitation | Workaround |
|---|---|
You might have trouble connecting the debugger to the Liberty runtime when you customize the Liberty install location in the build file. For example, if you use Maven and your pom.xml file contains a value like /Users/.../singleModMavenMP/myinstalldir/wlp for the <installDirectory> property, then Liberty is installed in the specified directory and the IDE debugger might not connect. |
Remove the configuration that specifies the custom location while you are debugging. You can restore this customization after debugging is complete. |
When you trigger completion (ctrl/cmd + space) in the featureManager section of the server.xml, and there is no prompt text already (e.g. <feature></feature>), all the features are listed, including some features with incompatible version numbers. If you subsequently type letters to filter the list, these incompatible version features may appear more prominently. |
If you type letters before triggering completion (ctrl/cmd + space), the expected filtering occurs and no features with incompatible version numbers will show. |
| Problem/Limitation | Workaround |
|---|---|
While editing a file, the underline associated with a warning or error diagnostic might occasionally appear out of sync with your code. 
|
If you encounter this problem, click on a different window and then return to IntelliJ. The diagnostics are refreshed. |
| Some diagnostic messages have associated quick fixes that on occasion fail to appear in the IDE. This problem can happen after you close all files and reopen a file of interest. | Exit the IDE and restart to reactivate quick fixes. |
rest_get and mpirc completion options always appear when you trigger completion (ctrl/cmd + space) in a Java file. |
You can ignore these suggestions when the cursor is not inside a class. |
| When you use a Gradle project with a space in the name (e.g. "my app") then Liberty Start does not work. | Remove the space from the project name. |
| Problem/Limitation | Workaround |
|---|---|
| When you run an action from the Liberty dashboard, the focus is not automatically pulled to the corresponding terminal window. For example, you might get confused if you are working in the Liberty terminal and then open a new terminal tab. If you execute an action from the Liberty dashboard, the action executes in the Liberty terminal tab, but the terminal window focus is now on the new terminal tab. Therefore, you might not see the action executing and wonder whether something went wrong. | To monitor the Liberty terminal, you might need to click it to give it focus before (or after) you execute the Liberty action. |