How to troubleshoot if Maven Project is not recognized by IntelliJ IDEA

Problem

When opening a maven project in IntelliJ IDEA, the project may not be recognized properly as expected. A proper maven project loaded in IntelliJ IDEA means:

1. Project Structure is synced automatically, following the settings of pom.xml in the project root. Source, test, resource folder and pom.xml file are displayed with the expected icon.
2. Module is added into the Maven tool window, and the lifecycle, plugins, dependencies are detected correctly.
3. Code inspection and highlighting work properly for the project, including the pom.xml, dependency resolution and other aspects.

However, due to some factors, after adding the maven project into IntelliJ IDEA, which leads the issue as below:

1. The Maven tool window is missing or empty
2. “Add as Maven Project” is missing in the context menu when right-clicking pom.xml ; Or even pom.xml is treated as a plain XML file (with “</>” icon instead of “m” icon).
3. Project opens as a plain Java project; For example, src/main/java and src/test/java are not marked as source/test roots.

General Expected Behavior

1. IDEA will detect the pom.xml if there is a pom.xml, in the context menu, the option “Add as a Maven project” will be displayed. After clicking this option, the pom.xml’s icon will be turned from </> to m.
2. The default lifecycle and repository will be shown in the Maven tool window even if the pom.xml is empty.
3. In the newer version of IntelliJ IDEA, the module information will be written to the system_directory/projects/project_name_hashcode/ and a data tree will be created in system_directory/Maven/Projects/hashcode/tree.dat.
4. IntelliJ IDEA will use .idea/misc.xml to understand whether this project is a maven project or not.

<component name="MavenProjectsManager">
  <option name="originalFiles">
    <list>
      <option value="$PROJECT_DIR$/pom.xml" />
    </list>
  </option>
</component>

Possible Solutions

The following action lists are just some general steps to troubleshoot the maven project recognition issue:

1. Go to Settings | Plugins | Installed, make sure the bundled Maven plugin is enabled.

2. Go to the Main Menu, View | Tool Windows | Maven is visible and open it to see the Maven tool window.

3. In the Project tool window, switch to the Project view. Right-click the pom.xml in project root and click “Add as Maven project”. The icon of pom.xml should be turned from </> to m with the default theme.

4. For an existing Maven project, go to Settings | Build, Execution, Deployment | Build Tools | Maven | Ignored Files and make sure pom.xml is not present or not checked in the list.

   Go to Settings | Editor | File Types | Ignored files and folders, make sure pom.xml and *.xml is not listed here.

5. Close the project, go to the project directory from Finder or File Explorer, then back up and remove .idea folder and <projectname>.iml file. Open IDEA, and go to File | Open, route to the project root directory, and click the pom.xml file, then click Open. Let the IDEA start the index and the project analyzing, it will automatically sync the project structure and module data.

6. Use local mvn to validate the project: run mvn validate in the project root inside Terminal / cmd / PowerShell. Make sure the structure is correct, and the pom.xml is correct.

7. Backup and remove the system directory, then reopen IntelliJ IDEA or use actions provided in step 5 to reopen the project.

8. Less possible: the bundled maven is broken, change to the customized maven directory for test. Or reinstall the IntelliJ IDEA for test.

Useful Logs

1. Add a diagnose option for maven log collection:
   1. Click Help | Diagnostic Tools | Debug Log Settings…
   2. Add the following entry in the dialog org.jetbrains.idea.maven:all::separate
   3. Reproduce the issue and capture the log via Help | Collect Logs and Diagnostic Data
2. The output of Run / Debug Console and Build Console. If run via Maven run configuration or maven command line, please add -X in command line to show extra output
3. build.log (located in Log Directory\build-log)
4. The .idea folder inside the issue project can be used to check the configuration data.