Fix the IntelliJ IDEA “./mvnw is not available” problem by first checking whether the project actually contains a Maven Wrapper, then decide whether IntelliJ should use the wrapper or a system Maven installation. If mvnw, mvnw.cmd, and .mvn/wrapper are missing, IntelliJ cannot run the wrapper, no matter how many times you reimport the project.

TLDR: Use Maven Wrapper when the project includes mvnw and the team needs the same Maven version on every machine. Use system Maven when the wrapper files are missing or broken, and you need a quick, stable local build. For example, in a 12 developer team, a wrapper can prevent version drift when 4 people have Maven 3.6, 5 have Maven 3.8, and 3 have Maven 3.9 installed. A typical fix takes under 5 minutes: check files, fix permissions, then set IntelliJ’s Maven home correctly.

What the error really means

When IntelliJ IDEA says ./mvnw is not available, it is not complaining about Maven in general. It is complaining about the Maven Wrapper script. That script is usually located at the root of the project:

  • mvnw for Linux and macOS
  • mvnw.cmd for Windows
  • .mvn/wrapper/maven-wrapper.properties for wrapper configuration
  • .mvn/wrapper/maven-wrapper.jar or a wrapper download setup, depending on the wrapper version

The catch is that IntelliJ may be set to run Maven through the wrapper even when the project does not have wrapper files. That mismatch creates the error. It feels silly, but this single setting can waste 20 minutes if you assume the problem is your pom.xml.

Maven Wrapper vs system Maven

Maven Wrapper is a project-level launcher. It downloads and runs the Maven version defined by the project. This is useful when build consistency matters. If the project says Maven 3.9.6, everyone gets Maven 3.9.6, even if their computer has another version installed.

System Maven is the Maven installation already available on your machine. It is usually installed through a package manager, an IDE bundle, SDKMAN, Homebrew, Chocolatey, or a manual ZIP installation. IntelliJ can point to this local Maven home and use it for all Maven projects.

Neither option is automatically better. The right choice depends on the project state.

  • Use Maven Wrapper when wrapper files exist and are committed to version control.
  • Use system Maven when wrapper files are absent, corrupted, blocked by permissions, or not used by the team.
  • Regenerate the wrapper when the project expects it but the files are incomplete.

First check: does the wrapper exist?

Go to the project root. This is the folder that contains pom.xml. Run one of these commands.

On macOS or Linux:

ls -la
ls -la .mvn/wrapper

On Windows PowerShell:

dir
dir .mvn\wrapper

If you do not see mvnw or mvnw.cmd, IntelliJ cannot use the wrapper. Switch IntelliJ to system Maven or add the wrapper properly.

If the files exist, test the wrapper outside IntelliJ. This removes the IDE from the problem.

On macOS or Linux:

./mvnw -v

On Windows:

mvnw.cmd -v

If the command fails in the terminal, IntelliJ is not the root cause. Fix the wrapper first.

Fix 1: switch IntelliJ to system Maven

This is the fastest fix when the wrapper is missing. It is also sensible for older enterprise projects that never adopted the Maven Wrapper.

  1. Open IntelliJ IDEA Settings.
  2. Go to Build, Execution, Deployment > Build Tools > Maven.
  3. Find Maven home path.
  4. Select your installed Maven path, or choose IntelliJ’s bundled Maven if available.
  5. Apply changes.
  6. Reload the Maven project from the Maven tool window.

Then verify from a terminal:

mvn -v

You should see a Maven version, Java version, and Maven home. If not, install Maven or correct your PATH.

On macOS with Homebrew, Maven is often installed with:

brew install maven

On Windows with Chocolatey:

choco install maven

On Linux, use your distribution’s package manager, or install Maven from the official Apache archive if you need a specific version.

Fix 2: repair wrapper permissions

On macOS and Linux, the wrapper script may exist but lack execute permission. This is common after ZIP downloads, file transfers, or odd Git settings. Honestly, it feels like a tiny permission bit has more power than the entire IDE.

Run:

chmod +x mvnw
./mvnw -v

If that works, go back to IntelliJ and reload the Maven project. If it still fails inside the IDE, check that IntelliJ is opening the correct project root. Opening a parent folder or a nested module can confuse wrapper detection.

Fix 3: regenerate the Maven Wrapper

If your team wants wrapper usage but the files are missing, generate them again. You need a working system Maven for this step.

mvn wrapper:wrapper

To request a specific Maven version:

mvn wrapper:wrapper -Dmaven=3.9.6

After generation, commit these files:

  • mvnw
  • mvnw.cmd
  • .mvn/wrapper/maven-wrapper.properties
  • Any required wrapper JAR or related wrapper files created by the plugin

Do not commit only part of the wrapper. Partial commits are a common cause of clean checkout failures. A build should work for a new developer after one clone and one command.

Fix 4: check Git ignore rules and line endings

Sometimes wrapper files exist on one machine but not in the repository. Check .gitignore. Make sure it is not excluding mvnw, mvnw.cmd, or the .mvn folder.

Line endings can also break scripts. On Windows, Git may change line endings in a way that causes Linux containers or CI jobs to fail with strange shell errors. Add or review .gitattributes if needed:

mvnw text eol=lf
mvnw.cmd text eol=crlf

This small setting can prevent failures in Docker, WSL, and CI agents.

Which option should a serious project use?

For most team projects, Maven Wrapper is the safer default. It reduces “works on my machine” problems. It also makes CI setup cleaner because the pipeline can run:

./mvnw clean verify

That said, system Maven is not wrong. It is practical for single developer projects, training code, internal prototypes, and legacy builds. It is also useful when a corporate proxy blocks wrapper downloads and the approved Maven installation is already managed by IT.

Use this simple rule:

  • Team project with CI: prefer Maven Wrapper.
  • Local quick fix: use system Maven.
  • Missing wrapper but project documentation mentions ./mvnw: regenerate the wrapper.
  • Wrapper exists but fails: test it in the terminal before changing IntelliJ settings.

IntelliJ checks that often get missed

If the error remains, inspect these settings:

  • Project SDK: Maven may fail if IntelliJ uses the wrong Java version.
  • Importer JDK: Check the JDK used for Maven importing.
  • Runner JRE: Maven runs may use a different JRE than expected.
  • Working directory: Make sure IntelliJ points at the folder containing pom.xml and mvnw.
  • Offline mode: Disable it if dependencies or wrapper files must be downloaded.

A reliable troubleshooting order

  1. Confirm the project root contains pom.xml.
  2. Check whether mvnw, mvnw.cmd, and .mvn/wrapper exist.
  3. Run ./mvnw -v or mvnw.cmd -v.
  4. If missing, switch IntelliJ to system Maven.
  5. If permissions fail, run chmod +x mvnw.
  6. If the team expects wrapper use, regenerate it and commit all wrapper files.
  7. Reload the Maven project in IntelliJ.

The serious fix is not to click random reimport buttons. Decide which Maven source the project should use. Then make IntelliJ match that decision. Once the wrapper or system Maven path is correct, most “./mvnw is not available” build failures disappear quickly.