Solution to the Maven submodule not displayed in the new version of IntelliJ IDEA

1. Problem phenomenon and background

When developing a Maven multi-module project using IntelliJ IDEA 2024 version, I found a confusing phenomenon: the child module of the parent module is not displayed in the Maven tool window on the right, only the parent module name (and no (root) identity). Previously, in the IntelliJ IDEA 2021 version, both the parent module and the child module could be displayed normally. After in-depth investigation, it was found that this problem is not limited to the 2024 version, but a typical scenario caused by the improvement of the standardization requirements for Maven configuration in newer versions (such as 2023.3 and above).

2. Analysis of core causes of the problem

1. Interface behavior changes in the new version of IntelliJ IDEA

The submodule list is not expanded by default：
The new version optimizes the display logic of the Maven project, by defaultThe parent module's child module will not expand automatically. You need to view the submodule through manual operations (such as double-clicking or clicking the expand arrow).
Strictly verify the effectiveness of the module：
New versionThe integrity check is stricter. If the configuration of the parent module or child module has problems such as empty labels and path errors, IDEA may directly hide the invalid module.

2. Maven multi-module project configuration requirements

Maven multi-module project needs to meet the following conditions:

Parent module's<packaging>Must bepom：

<packaging>pom</packaging>

The submodule must be in the parent module<modules>Statement in the：

&lt;modules&gt;  
    &lt;module&gt;Submodule directory name&lt;/module&gt;  
&lt;/modules&gt;

SubmoduleMust inherit the parent module：

&lt;parent&gt;  
    &lt;groupId&gt;Parent module'sgroupId&lt;/groupId&gt;  
    &lt;artifactId&gt;Parent module'sartifactId&lt;/artifactId&gt;  
    &lt;version&gt;Version number&lt;/version&gt;  
    &lt;relativePath&gt;../&lt;/relativePath&gt;  
&lt;/parent&gt;

3. Impact of empty tags and invalid configurations

Empty tags (such as<url/>、<license/>）：
Although Maven allows these tags to be optional, empty tags may causeResolve warnings or errors, the new version of IDEA is more sensitive to this and may directly ignore the entire module.
Path error：
like<module>The directory name in the tag is inconsistent with the actual submodule path (such asdkand actual directorydk-moduleDoes not match), the submodule will not be recognized.

3. Solutions and operation steps

Step 1: Check and repair the parent module’s

make sure<packaging>correct：

<packaging>pom</packaging>

Supplement the value of the empty tag：
Remove or add placeholder content, for example:

<url></url>  
<licenses>  
    <license>  
        <name>Apache 2.0</name>  
        <url>/licenses/LICENSE-2.</url>  
    </license>  
</licenses>

verify<modules>Statement：
Ensure the submodule directory name and<module>The label is consistent:

<modules>  
    <module>dk</module>  
</modules>

Step 2: Check the submodule’s

Inheriting the parent module configuration：
Ensure submoduleInclude:

<parent>  
    <groupId></groupId>  
    <artifactId>occupationalHealth</artifactId>  
    <version>0.0.1-SNAPSHOT</version>  
    <relativePath>../</relativePath>  
</parent>

Basic information statement：
Even if the parent module is inherited, the child module still needs to be explicitly declared.artifactId：

<artifactId>dk</artifactId>

Step 3: Re-import the project in IntelliJ IDEA

Force refresh of Maven project：
- OpenMaven Tool Window（View → Tool Windows → Maven）。
- Click on the topReimport All Maven Projects(Refresh icon).
Manually expand parent module node：
- In the Maven tool window,Double-click the parent module nameOr clickExpand the arrow（>), view the submodule list.
Clean the cache and restart：
- After closing the project, delete it.ideaFolders and*.imldocument.
- Restart IDEA and reimport the project.

Step 4: Verify the project structure on the command line

Run the following command to check whether Maven recognizes submodules:

mvn clean install -X

If the output contains the construction information of the submodule (such asBuilding dk 0.0.1-SNAPSHOT), then the configuration is correct.
If an error is reported, it will be located according to the log location problem (such as path errors, dependency missing).

4. Technical principles and extended knowledge

1. Maven multi-module project mechanism

The role of the parent module：
Parent module passes<modules>Declare submodules and uniformly manage dependencies, plug-ins and configurations.
Submodule inheritance：
Submodules inherit from parent modulegroupId、versionetc., but need to be explicitly declaredartifactId。

2. IntelliJ IDEA's Maven plugin behavior

Automatic import vs manual import：
IDEA enables automatic import by default, but if the configuration is incorrect, it needs to be triggered manually.Reimport。
Cache mechanism：
IDEA will cache the project structure and delete it.ideaFolders can force re-parse projects.

3. Potential risks of empty tags

Maven strictly follows the specifications for parsing XML, and empty tags may lead to:

Analyze warning:like<url/>Will be considered invalid, but the project can still be built.
IDEA Hide Module: New version of IDEA may directly filter invalid modules to avoid displaying incorrect structures.

5. Frequently Asked Questions and Answers

Q1: What should I do if the parent module does not have a (root) logo?

reason: The parent module is not recognized as the root module.
solve：
1. Ensure the parent module'sInclude<packaging>pom</packaging>。
2. Right-click the parent module in the Maven tool window and selectAdd as Root。

Q2: The submodule path is correct but not displayed?

reason:IDEA The parent module node is not expanded.
solve: Double-click the parent module name or click the Expand arrow.

Q3: How to quickly verify whether the parent module is valid?

method：

mvn help:effective-pom -f Parent module/

Check whether the output contains<modules>part.

6. Best practices and summary

1. Configuration specification suggestions

Avoid empty tags: Provides placeholder values for all optional tags.
Path consistency:make sure<module>The tag is exactly the same as the actual directory name (case sensitive).
Dependency management: The parent module manages the dependency version uniformly, and the child module passes<dependencyManagement>Inheritance.

2. Precautions for version upgrade

IDEA new version features：
- Submodules are not expanded by default and require manual operation.
- Strengthen configuration verification, empty tags may cause modules to be hidden.
Compatibility check：
When building a new project, it is recommended toFile → Project StructureSettingsMavenCompatibility options.

The above is the detailed content of the solution that does not display the Maven submodule in the new version of IntelliJ IDEA. For more information about the IDEA Maven submodule not display, please follow my other related articles!