A Practical Guide to Maven Java Projects in NetBeans: POM, Dependencies, and Build Lifecycle

Desired Outcome

Many Java teams adopt Maven to eliminate environment-specific build scripts, only to discover that IDE-specific settings still leak into the project. In NetBeans, the reliable approach is to treat the Project Object Model (POM) file as the authoritative configuration and use the IDE only as a front-end for Maven. This guide walks through creating a Maven Java Application, adding a dependency, and verifying that the build lifecycle behaves identically on any machine.

Prerequisites

• A supported JDK installed and registered in NetBeans. Maven uses the JDK to compile and run tests.
• NetBeans with Java SE support. Recent NetBeans distributions bundle Apache Maven, so a separate installation is usually unnecessary. If you use an external Maven, point NetBeans to it in Tools > Options > Java > Maven.
• Network access to Maven Central or your organization's artifact repository. If you sit behind a proxy, configure it in the same Maven options panel before creating the project.

Create the Project and Inspect the POM

In NetBeans, choose File > New Project, select Java with Maven in the category list, then Java Application. Click Next, enter a Project Name, and accept the generated Group Id, Version, and Package. Click Finish.

Open the Projects window, expand the Project Files node, and double-click pom.xml. The editor shows the XML source and a graphical POM viewer. The initial POM contains a <properties> block that may set a source and target encoding, a <dependencies> section, and a <build> section. Every change you make through the IDE's Project Properties dialog ultimately writes into this file.

Add a Dependency

To add JUnit for testing, edit the POM directly or use the GUI. In the graphical viewer, click Add in the Dependencies section, search for junit:junit, and select a version compatible with your JDK. NetBeans writes the corresponding XML:

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.13.2</version>
  <scope>test</scope>
</dependency>

The test scope tells Maven the JAR is required for compilation and execution of tests but is not packaged with the application. After saving, NetBeans resolves the artifact and adds it to the project classpath automatically.

Map the JDK Version Deliberately

NetBeans Project Properties dialogs let you pick a Java platform for compilation. That choice is synchronized into the POM, typically through the maven-compiler-plugin configuration or the maven.compiler.source and maven.compiler.target properties. If the POM requests a bytecode version newer than the JDK registered in the IDE, the compiler emits an Unsupported Class Version error at runtime. To avoid this, set the source and target explicitly in the POM rather than relying on the IDE default:

<properties>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

Replace 17 with the major version of the JDK you intend to use. Verify that the same JDK is selected under Project Properties > Sources and under Tools > Options > Java > Maven if you run Maven from the IDE.

Run Clean and Build

Right-click the project node and choose Clean and Build. NetBeans invokes the Maven lifecycle phases clean, compile, test, and package in order. The integrated Maven output window streams the same log you would see in a terminal, including plugin download messages and test results. Because the phases run in a fixed sequence, a successful build proves that compilation succeeded, tests passed, and an artifact was produced.

Expected Checks

After the build finishes, verify the result concretely:

• Expand the target directory in the Files window. You should find classes/ containing compiled .class files and a JAR named after the project artifact.
• Open the Test Results window. If you added a JUnit test, NetBeans should display a green tree with the number of tests run.
• Check the Maven output window for BUILD SUCCESS. A failure here is the authoritative signal, even if the IDE shows no error dialog.

Recovery Options for Common Failures

Unsupported Class Version Errors

If execution fails with a message about an unsupported major version, the compiled bytecode exceeds the runtime JDK. Open the POM and confirm that maven.compiler.source and maven.compiler.target match the JDK selected in Project Properties > Sources. Then run Clean and Build again to force recompilation.

Dependency Resolution Failures

When Maven cannot download an artifact, the output window reports a resolution error. Check that your proxy settings in Tools > Options > Java > Maven match your network environment. If the local repository is corrupted, delete the artifact directory under ~/.m2/repository (or the path configured in settings.xml) and rebuild. NetBeans will re-download the JAR on the next resolution.

XML Formatting Drift from GUI Edits

Heavy use of the Project Properties dialog can occasionally reorder elements or change indentation in the POM. If the file becomes hard to read, copy the meaningful content into a clean pom.xml template and re-enter the dependency and plugin declarations. Always keep the POM under version control so formatting changes are visible in diffs.

Limitations and Verification

This workflow assumes a NetBeans release that bundles or supports Apache Maven and a JDK compatible with the Maven plugins in use. NetBeans versions and bundled Maven versions change over time; if a plugin behaves unexpectedly, run mvn -v in the NetBeans terminal tab to see which Maven and JDK the IDE is actually using.

To verify the project is truly portable, copy the project directory to a second machine (or delete the target folder locally), run Clean and Build, and confirm that tests pass and the same JAR is produced without manual classpath adjustments. If the build succeeds from the POM alone, the IDE is acting as a Maven front-end rather than storing hidden configuration.