Java Beginner

Maven Tutorial for Beginners: Mastering Java Build Automation

📅 March 09, 2026 ⏱ 4 min read 🎯 Beginner

Where developers are forged. · Structured learning · Free forever.

📍 Part of: Build Tools → Topic 1 of 5

A comprehensive guide to Maven for Beginners — master the Project Object Model (POM), build lifecycles, GAV coordinates, and dependency management in Java.

🧑‍💻 Beginner-friendly — no prior Java experience needed

In this tutorial, you'll learn

A comprehensive guide to Maven for Beginners — master the Project Object Model (POM), build lifecycles, GAV coordinates, and dependency management in Java.

Maven's value is not in any individual feature — it's in the consistent contract it creates between developers, CI systems, and tooling. One pom.xml, one command, one predictable outcome.
The 'Convention over Configuration' principle means your pom.xml should be as small as possible. Every line of configuration you add is a default you're overriding, and every override is a potential source of future confusion for the next engineer.
GAV coordinates are not just metadata — they are the addressing system for the entire Maven artifact ecosystem. Treat them as a public API: once you publish a release version, the artifact at those coordinates must never change.

✦ Plain-English analogy ✦ Real code with output ✦ Interview questions

⚡Quick Answer

Maven is a declarative build tool and dependency manager for Java — you describe what you need in pom.xml and it handles the rest
GAV coordinates (GroupId, ArtifactId, Version) uniquely identify every artifact in the Maven ecosystem
The standard directory layout (src/main/java, src/test/java) is mandatory by convention — Maven ignores files placed elsewhere
Build lifecycles are ordered phases: running 'mvn package' automatically triggers compile and test first
Transitive dependencies are resolved automatically — Library A's dependency on Library B is pulled in without you declaring it
The biggest trap: hardcoding local file paths in pom.xml breaks the build for every teammate and every CI server

🚨 START HERE

Maven Emergency Debug Cheat Sheet

When Maven builds break in production CI/CD pipelines, run these commands in order. Each block treats a specific failure mode — don't start at the bottom and work up, start at the symptom that matches yours.

🟡Build fails with dependency resolution errors — artifact cannot be found or download checksum fails

Immediate ActionForce-update all dependencies and purge the local cache for the failing artifact. Maven's local cache can hold corrupted or partial downloads that cause resolution to fail indefinitely.

Commands

mvn dependency:purge-local-repository -DactTransitively=false -DreResolve=true

mvn dependency:resolve -U

Fix NowIf resolution still fails, verify the artifact actually exists in the remote repository: mvn dependency:get -Dartifact=groupId:artifactId:version. If that returns 404, the artifact doesn't exist at that version in your configured repositories. Check ~/.m2/settings.xml for correct repository URLs and confirm your proxy or VPN is not blocking the request.

🟡Build passes locally but fails on CI — same code, different outcome

Immediate ActionDump the full effective dependency tree on both environments and diff them. Do not assume infrastructure until you've ruled out dependency drift.

Commands

mvn dependency:tree -Dverbose > deps-local.txt

mvn help:effective-pom > effective-pom.xml

Fix NowDiff deps-local.txt against the equivalent output captured on CI. Look for version mismatches in any transitive dependency, SNAPSHOT versions that could have been updated overnight, and any <exclusion> that appears locally but not in CI. Check effective-pom.xml for active profiles — different profiles may be activating on different environments and changing dependency resolution.

🔴OutOfMemoryError or build timeout on CI — build succeeds locally with default settings

Immediate ActionIncrease Maven heap and optionally enable parallel module execution to reduce wall-clock build time.

Commands

export MAVEN_OPTS='-Xmx4096m -XX:+UseG1GC -XX:+UseContainerSupport'

mvn clean install -T 2C

Fix Now-T 2C runs two threads per available CPU core — safe for most multi-module projects where modules have clean dependency separation. If you're not sure whether modules have hidden inter-dependencies, use -T 1C first. To isolate whether the bottleneck is compilation or test execution, add -DskipTests to the command and measure whether the time improves meaningfully. If it does, the tests are the bottleneck and you need to look at test parallelism in the Surefire plugin configuration.

🟡Plugin execution fails with 'No compiler is provided in this environment' or 'tools.jar not found'

Immediate ActionConfirm JAVA_HOME points to a JDK installation, not a JRE. Maven's compiler plugin requires javac, which only exists in a JDK. A JRE contains only java.

Commands

echo $JAVA_HOME && $JAVA_HOME/bin/javac -version

mvn help:active-profiles

Fix NowIf JAVA_HOME points to a path like /usr/lib/jvm/java-17-openjdk-amd64/jre, update it to /usr/lib/jvm/java-17-openjdk-amd64. If your project uses Maven Toolchains to manage JDK versions explicitly, verify the toolchains.xml at ~/.m2/toolchains.xml has the correct JDK path and that the requested JDK version in pom.xml matches what's installed on the machine.

Production IncidentSnapshot dependency breaks CI — builds pass locally but fail on JenkinsA developer added a dependency on a SNAPSHOT version of an internal library. Builds worked locally because the developer's machine cached the latest snapshot. On Jenkins, the snapshot resolver pulled a different — and broken — build from the remote repository, causing the CI pipeline to fail silently for three days before anyone noticed. The kicker: no application code had changed in that window.

SymptomCI builds fail with ClassNotFoundException for a class that exists and compiles cleanly on every developer workstation. The error appears exclusively on the Jenkins agent. Running 'mvn clean install' locally produces a green build every time. The broken class is clearly present in the source — you can open it in your IDE.

AssumptionThe team's first assumption was a corrupted local repository cache on the Jenkins agent. They ran 'mvn clean' on the agent and retried — still failing. The second assumption was network-level corruption: maybe the proxy was mangling the downloaded JAR. They added checksum verification and reran. Still failing. Three hours of investigation aimed at infrastructure, and the actual problem was sitting quietly in the pom.xml the whole time.

Root causeA transitive dependency was declared with version '1.0-SNAPSHOT'. SNAPSHOT versions in Maven are explicitly mutable by design — the remote repository can publish a new build artifact under the same version string at any time, and consumers are expected to pull the latest. The developer's local ~/.m2/repository had a cached copy from two days prior that compiled and ran correctly. Jenkins, configured with a shorter snapshot cache TTL, pulled the latest SNAPSHOT published four hours before the failing build. That snapshot contained a breaking API change: a class had been removed from the public surface by its maintainer without a version bump, because SNAPSHOT semantics permit exactly that. The pom.xml had no version pinning, no repository policy controlling SNAPSHOT update frequency, and no CI step that could detect the dependency drift.

Fix1. Pin the dependency to a release version — 1.0 instead of 1.0-SNAPSHOT. This is the correct fix for anything on a release or main branch. 2. If a SNAPSHOT is genuinely required during active development, add <updatePolicy>always</updatePolicy> in the repository configuration so both local and CI resolve from the same point in time. This doesn't fix mutability but at least makes the behavior consistent. 3. Better: route all artifact resolution through a Nexus or Artifactory proxy configured to cache a specific snapshot timestamp and serve it consistently to all consumers. 4. Add a CI step that runs 'mvn dependency:tree' and diffs its output against the last successful build. Any dependency that changed between two builds with no pom.xml change is a signal worth flagging before it becomes a production incident.

Key Lesson

SNAPSHOT versions are mutable by contract — the same version string can and will resolve to different JARs over time, sometimes within hoursNever use SNAPSHOT dependencies on release or main branches — pin to release versions without exceptionLocal ~/.m2/repository caches artifacts indefinitely by default, which masks dependency issues that are immediately visible on a clean CI agentWhen a build fails on CI but not locally, check the dependency tree before assuming infrastructure problems — the answer is usually in the pom.xmlAdd dependency tree diffing to your CI pipeline so dependency drift is caught automatically rather than discovered during an incident

Production Debug GuideThe failures that actually happen in production pipelines, and the commands that diagnose them

Build passes locally but fails on CI with ClassNotFoundException or NoSuchMethodError→Compare dependency trees between environments. Run 'mvn dependency:tree -Dverbose' locally and capture the CI output. Diff them line by line. You are looking for version mismatches in transitive dependencies — particularly anything listed as SNAPSHOT. ClassNotFoundException usually means a class was removed; NoSuchMethodError usually means the wrong version of a class was loaded from a conflicting transitive dependency.

Build hangs indefinitely during dependency resolution with no output→This is almost always a network or proxy issue. Run 'mvn dependency:resolve -U' with Maven's debug flag (-X) to see exactly which repository it's trying to reach and where it stalls. Check whether a corporate firewall or forward proxy is blocking outbound connections to Maven Central (repo1.maven.org). Verify that ~/.m2/settings.xml has the correct proxy stanza — host, port, username, password, and nonProxyHosts. If you're behind a corporate proxy and settings.xml is unconfigured, Maven will hang silently.

'Non-resolvable parent POM' error in a multi-module project→This typically means Maven cannot locate the parent POM before it can parse the child. In a local multi-module setup, run 'mvn install' on the parent POM first, then build child modules. Verify the <relativePath> element in the child POM points to the correct relative location of the parent pom.xml. If the parent POM comes from a remote repository, confirm that repository is declared in settings.xml — it cannot be declared in the child POM because Maven hasn't finished reading it yet.

Compilation succeeds but tests fail with 'No tests were found' or zero tests run→First, verify test classes live in src/test/java and not in src/main/java. Second, check that test class names match Maven Surefire's default pattern: classes must end with Test, Tests, or TestCase, or begin with Test. Surefire will silently skip everything that doesn't match. Third, verify the JUnit dependency has <scope>test</scope> — if it's on the compile scope, it's present but Surefire may not recognize it depending on JUnit version. For JUnit 5, also verify junit-jupiter-engine is on the test classpath alongside junit-jupiter-api.

OutOfMemoryError during Maven build on CI→Set MAVEN_OPTS='-Xmx4096m -XX:+UseG1GC' before invoking Maven. In containerized CI environments, also ensure the JVM is container-aware — add -XX:+UseContainerSupport if running Java 11 or later inside Docker to prevent the JVM from reading host machine RAM instead of container limits. If the OOM happens during compilation of large projects, the culprit is often the annotation processor heap, not the application code. Add <compilerArgs><arg>-J-Xmx2g</arg></compilerArgs> to the compiler plugin configuration.

Dependency conflict — wrong version of a library is loaded at runtime despite pinning→Run 'mvn dependency:tree -Dverbose' and specifically look for lines marked with 'omitted for conflict with' or 'omitted for duplicate.' These tell you which version was selected and which was dropped. If the wrong version is winning via Maven's nearest-definition rule, add the correct version to your pom.xml directly — making it the nearest definition — or use <dependencyManagement> in a parent POM to force a specific version across the entire dependency graph. <exclusions> is a last resort: it removes a transitive dependency entirely, so use it only when you're certain nothing else in the classpath needs it.

Apache Maven has been part of the Java ecosystem since 2004, and if you've worked on more than one Java project professionally, you've almost certainly encountered it — even if you didn't realize you were looking at it. It shows up as that pom.xml file in the root of the repository that nobody wants to touch.

But Maven is worth understanding properly, not just cargo-culting from project to project. It is a project management and build comprehension tool that gives every Java project a uniform structure, a consistent build process, and a declarative way to express external dependencies. When it works correctly — which is most of the time — it's invisible. When it breaks, and it will break, knowing what's actually happening underneath saves you hours.

This guide is written from the perspective of someone who has debugged Maven builds at 11pm before a production release, reviewed dozens of pom.xml files in code reviews, and watched teams make the same five mistakes across completely different organizations. We'll cover what Maven is, the mental models you need to reason about it correctly, real failure modes from production environments, and the practical mechanics of pom.xml, lifecycles, and dependency management.

By the end, you'll have both the conceptual foundation and the hands-on examples to use Maven with confidence — and more importantly, to debug it when something goes wrong.

What Is Maven and Why Does It Exist?

Before Maven, every Java project was its own small build systems problem. One team used Ant scripts with manually maintained lib/ folders full of JARs checked into version control. Another team used shell scripts that only worked on specific operating systems. A third team had a README with 14 manual steps that was already three months out of date. Adding a new developer to any of these projects meant a half-day of setup friction at minimum.

Apache Maven was created to solve build fragmentation across the entire Java ecosystem with a single architectural decision: Convention over Configuration. Instead of each project defining how to build itself, Maven defines one correct way to build any Java project. Your source code goes in src/main/java. Your tests go in src/test/java. Your compiled output goes to target/. Your project is described in pom.xml using a declarative format that says what you need, not how to produce it.

The consequence of this is significant: a developer who has never seen your project before can run 'mvn clean install' and get a working build. No README archaeology required. No environment-specific setup scripts. CI/CD systems like Jenkins and GitHub Actions rely on exactly this contract — they know how to build Maven projects without per-project configuration because Maven projects all work the same way.

The other half of what Maven does is dependency management. Before centralized repositories, you literally emailed people for JAR files or downloaded them from project websites. Maven Central changed that. You declare a dependency by its GAV coordinates in pom.xml, and Maven fetches it — along with everything that dependency needs — automatically. The transitive dependency resolution that feels obvious today was genuinely novel when Maven introduced it.

pom.xml · XML

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!--
      GAV coordinates: the unique address of this artifact in the Maven ecosystem.
      GroupId follows reverse-domain convention (like Java package names).
      ArtifactId is the specific module name.
      Version uses SNAPSHOT during development, release versions for production.
    -->
    <groupId>io.thecodeforge</groupId>
    <artifactId>forge-starter-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <!-- Compiler source/target must be explicit.
             Defaulting to Java 5 compatibility is the Super POM's default
             and will cause surprises on modern JDKs. -->
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!--
          Runtime dependency: available in all classpaths.
          commons-lang3 provides StringUtils, Validate, and other
          utilities that augment java.lang.
        -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.14.0</version>
        </dependency>

        <!--
          Test-scoped dependency: available only during test compilation
          and execution. Never shipped in the production JAR.
          JUnit 5 requires both the API (for writing tests)
          and the engine (for running them via Surefire).
        -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>5.10.2</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>5.10.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!--
              Maven Surefire runs unit tests during the 'test' phase.
              Version 3.x is required for JUnit 5 support.
              Without this explicit version, the Super POM's default
              Surefire version (2.x) will silently skip all JUnit 5 tests.
            -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.2.5</version>
            </plugin>
        </plugins>
    </build>
</project>

▶ Output

[INFO] BUILD SUCCESS
[INFO] Total time: 4.823 s
[INFO] Finished at: 2026-03-09T10:15:32Z

# Maven resolved commons-lang3 and JUnit from Maven Central,
# compiled src/main/java to target/classes,
# compiled src/test/java to target/test-classes,
# ran tests via Surefire, and packaged the result to
# target/forge-starter-app-1.0-SNAPSHOT.jar

Mental Model

Convention over Configuration — The Contract You're Signing

Maven makes one strong promise: follow the conventions and you get a working build with minimal configuration. Break the conventions and you're responsible for overriding every assumption Maven made on your behalf.

Standard directory layout is non-negotiable for zero-config builds: src/main/java for source, src/test/java for tests, src/main/resources for non-Java assets — Maven scans exactly these paths and nowhere else
pom.xml is declarative, not procedural: you list what you need, Maven's plugins decide how to produce it — this is why pom.xml is readable by someone who has never run the build
The Super POM is Maven's hidden foundation: every pom.xml silently inherits compiler settings, plugin versions, and repository URLs from a built-in parent — it's why a four-line pom.xml can compile a project at all
Lifecycle phases are ordered and cumulative: 'mvn package' always runs validate, compile, and test first — you cannot run package and skip compile, by design
Overriding conventions is always possible but always has a cost: you must document every override, because the next engineer to read your pom.xml will assume conventions unless told otherwise

📊 Production Insight

The most expensive Maven problems I've seen in production were not technical — they were organizational. A team deviated from the standard directory layout 'just this once' for a legacy module integration. Six months later, four different CI configurations existed to handle the exception. New team members consistently got the build wrong on first setup.

Maven's conventions are valuable precisely because they are boring and universal. If you find yourself fighting them, the correct question is whether the deviation is genuinely necessary or whether the underlying code organization problem should be fixed instead.

Rule: treat any pom.xml deviation from convention as technical debt. Document it with a comment explaining why it exists and what it would take to remove it.

🎯 Key Takeaway

Maven exists to eliminate the build fragmentation that made every pre-Maven Java project a unique setup puzzle. The Convention over Configuration philosophy is not a limitation — it's the product. Consistent, predictable builds across every developer machine and every CI server is the entire value proposition.

The pom.xml is not a build script. It's a project description. The difference matters: a build script tells Maven how to compile your code. A project description tells Maven what your project is, and Maven figures out the how.

Punchline: if your project follows the standard directory layout and you've declared your dependencies correctly, Maven needs exactly one command to compile, test, and package your code — and that command is the same across every project in the ecosystem.

When to Reach for Maven

IfJava project with external dependencies, team of 2+ developers, or CI/CD pipeline

→

UseUse Maven — standardized builds eliminate environment-specific failures and the dependency resolver handles transitive graph resolution you don't want to manage manually

IfSingle-file Java script with no external dependencies and no tests

→

UseSkip Maven entirely — 'javac MyScript.java && java MyScript' is sufficient, and adding a build tool here is engineering theater

IfProject with complex conditional build logic, custom task graphs, or polyglot (Java + Kotlin + Groovy) modules

→

UseEvaluate Gradle — Maven's XML lifecycle model is rigid and conditional logic in pom.xml profiles becomes unmaintainable beyond moderate complexity

IfNeed to publish a library artifact to a shared team repository

→

UseUse Maven — the deploy lifecycle with Nexus or Artifactory is a solved problem, and GAV coordinates give your artifact a globally unique, addressable identity

IfInheriting an existing project that already uses Maven

→

UseKeep Maven unless migration to another tool has a clear ROI — fighting the existing build system during feature development is almost never worth the context switch

Common Mistakes and How to Avoid Them

After reviewing a few hundred pom.xml files across different teams and organizations, the failure patterns are remarkably consistent. The same five or six mistakes appear regardless of team size, company, or project domain. Understanding them in advance is worth more than discovering them through production incidents.

The most frequent mistake is misunderstanding what 'Convention over Configuration' actually means in practice. It means Maven has already decided where your code lives, how it gets compiled, and what gets packaged. If you put your Java files in the wrong directory — even by one level — Maven compiles successfully and produces an empty JAR. It does not warn you. The build is green and the artifact is wrong. This particular failure mode is subtle enough to ship to CI before anyone notices.

The second most common mistake is dependency scope confusion. A dependency without an explicit <scope> defaults to compile scope — it is present at compile time, test time, and it ships inside your final artifact. Test frameworks (JUnit, Mockito, TestContainers) must be declared with <scope>test</scope> or they end up in your production JAR, inflating its size and adding transitive dependencies you don't need in production. The same logic applies to <scope>provided</scope> for libraries supplied by the runtime container — if your application runs in Tomcat, the Servlet API should be provided-scoped, not compile-scoped.

Transitive dependency conflicts are the third pattern, and they're the most insidious because they often don't surface during compilation. They appear at runtime as NoSuchMethodError or ClassNotFoundException when the JVM loads a class from the wrong version of a library. The diagnosis requires 'mvn dependency:tree -Dverbose' and some patience reading the output.

standard-layout.txt · BASH

1234567891011121314151617181920212223

# io.thecodeforge: Standard Maven Project Layout
# This is the contract Maven enforces. Deviate from it and you
# override defaults in pom.xml. Override defaults and you document why.

my-app/
├── pom.xml                    # Project descriptor — the only required file
├── target/                    # Maven-managed output directory — never commit this
│   ├── classes/               # Compiled .class files from src/main/java
│   ├── test-classes/          # Compiled .class files from src/test/java
│   └── my-app-1.0-SNAPSHOT.jar
└── src/
    ├── main/
    │   ├── java/              # Production Java source — io/thecodeforge/app/Main.java
    │   └── resources/         # Non-Java resources copied to classpath root:
    │                          # application.properties, logback.xml, META-INF/
    └── test/
        ├── java/              # Test classes — must end with 'Test' for Surefire
        └── resources/         # Test-only configuration — overrides main resources
                               # during test execution

# Critical: Maven scans only these directories.
# A Java file placed in src/java/ or src/com/ will compile if
# you call javac directly but will be invisible to Maven.

▶ Output

# Running 'mvn clean package' against this structure:
# [INFO] Compiling 3 source files to target/classes
# [INFO] Running io.thecodeforge.app.MainTest
# [INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
# [INFO] BUILD SUCCESS

⚠ The Mistake That Doesn't Fail Loudly

Placing source files outside src/main/java does not cause a build failure. Maven simply doesn't see them. The build succeeds, the JAR is produced, and the missing classes are discovered at runtime — often in production. Always verify your directory layout matches the Maven convention before assuming the build is correct.

📊 Production Insight

The dependency bloat problem compounds quietly over time. A project that starts with 8 well-scoped dependencies can accumulate 40 transitive dependencies over 18 months as the team adds libraries for individual convenience methods. Each unnecessary dependency is an expanded attack surface, a potential version conflict, and additional bytes in every deployed artifact.

I've seen projects where 'mvn dependency:analyze' reported that 60% of declared dependencies were either unused in the code or available transitively through another declared dependency. Neither of those is technically broken, but both are maintenance debt.

Rule: run 'mvn dependency:analyze' in code review for any PR that adds a new dependency. Unused declared dependencies should be removed. Dependencies used but undeclared should be declared explicitly — don't rely on transitive resolution for things you're directly importing in your own code.

🎯 Key Takeaway

The standard directory layout is not a suggestion — it's the contract that makes Convention over Configuration work. Files outside the expected paths are invisible to Maven, which produces green builds with incorrect artifacts.

Dependency scope is a correctness concern, not just an organization preference. Test dependencies that ship in production artifacts, and provided dependencies declared as compile-scoped, are both sources of runtime failures that compile-time checks won't catch.

Punchline: run 'mvn dependency:analyze' as part of your standard code review process. The output tells you exactly which dependencies are doing nothing and which direct imports you're relying on transitively — both of which are problems waiting to happen.

Dependency Scope and Version Decisions

IfAdding a dependency for one utility method that already exists in commons-lang or Guava

→

UseCheck your existing dependencies first — you may already have access to equivalent functionality transitively. Adding a whole library for one method is almost never justified.

IfTwo dependencies pull in different versions of the same transitive library

→

UseUse <dependencyManagement> in your parent or project POM to enforce a single version across the dependency graph. <exclusions> is appropriate when you need to remove a transitive dependency entirely, not just override its version.

IfA dependency is only used in test code — JUnit, Mockito, TestContainers, H2

→

UseDeclare it with <scope>test</scope>. It must never ship in the production artifact. This is not optional — it's a correctness issue, not just a size optimization.

IfA library is provided by the runtime container — Servlet API in Tomcat, Jakarta EE APIs in WildFly

→

UseUse <scope>provided</scope>. If you declare it as compile-scoped, you may ship a version that conflicts with the container's version, causing ClassCastException at runtime despite a clean build.

IfUsing a SNAPSHOT version on a release or main branch

→

UseStop. Pin to a release version unconditionally. SNAPSHOT semantics permit the remote repository to change the artifact under the same version string. On a release branch, that is an unacceptable risk.

🗂 Manual Build vs Maven Build

Why Maven replaced custom build scripts — and what that decision actually costs and saves

Aspect	Manual Build (No Maven)	With Maven
Dependency Management	Manual JAR downloads into a lib/ folder. JARs committed to version control. Each developer manually tracks which version of what is in the folder and why.	Declared in pom.xml by GAV coordinates. Maven fetches from Central automatically. Versions are explicit, auditable, and diffable in code review.
Build Steps	Custom shell or batch scripts, unique to each project. A new developer must read and understand the script before running anything. Scripts break on new OS versions.	Standardized lifecycle phases — validate, compile, test, package, install, deploy. Every Maven project uses the same command sequence. Zero documentation required for standard operations.
Project Structure	Varies by developer preference, team habit, and project history. Three projects on the same team may use three different layouts. Onboarding requires per-project orientation.	Uniform by convention. src/main/java, src/test/java, src/main/resources — every Maven project looks the same. A developer familiar with one Maven project can navigate any other immediately.
Multi-module support	Manually coordinate build order across modules. One module's compile output must be manually placed where another module can find it. Build scripts become fragile as the module graph grows.	Declared in a parent POM with <modules>. Maven resolves the correct build order from the dependency graph automatically. 'mvn install' on the parent builds every module in the right sequence.
Environment Portability	Works on the machine it was written on. CI requires custom setup to match the developer's environment. 'Works on my machine' is a real and recurring problem.	Portable to any machine with Maven installed. Dependency versions are locked in pom.xml. CI runs 'mvn clean install' and produces an identical artifact regardless of the agent's history.
Audit and Reproducibility	No standard mechanism to know exactly which JAR versions were used in a given build. Reproducing a specific build artifact six months later is often impossible.	The pom.xml at a specific Git commit fully describes the artifact produced by that commit. Reproducing a past build means checking out the commit and running 'mvn clean package' — assuming snapshot drift hasn't occurred.

🎯 Key Takeaways

Maven's value is not in any individual feature — it's in the consistent contract it creates between developers, CI systems, and tooling. One pom.xml, one command, one predictable outcome.
The 'Convention over Configuration' principle means your pom.xml should be as small as possible. Every line of configuration you add is a default you're overriding, and every override is a potential source of future confusion for the next engineer.
GAV coordinates are not just metadata — they are the addressing system for the entire Maven artifact ecosystem. Treat them as a public API: once you publish a release version, the artifact at those coordinates must never change.
Lifecycle phases are cumulative and ordered within a lifecycle. 'mvn package' always runs compile and test first. Understanding this prevents wasted time adding flags to skip phases that would have run anyway.
The Super POM is the silent foundation of every Maven build. Before debugging a behavior you didn't configure, run 'mvn help:effective-pom' to see the full resolved configuration including everything inherited from the Super POM and any parent POMs.
Read the official Maven documentation for the plugins you actually use — the maven-compiler-plugin reference, the maven-surefire-plugin reference, the dependency plugin documentation. Tutorials cover the happy path. The official docs cover the edge cases that become production incidents.

⚠ Common Mistakes to Avoid

✕Overusing Maven for trivial projects

Symptom

A developer creates a multi-module pom.xml with a parent POM, Maven profiles for dev/staging/prod, and six plugin configurations for a 'Hello World' program with no external dependencies. The project is 30 lines of application code and 200 lines of build configuration. Setting it up takes longer than writing the code, and the next person to touch it spends 20 minutes understanding the build structure before reading any application logic.

Fix

Match the tool to the problem. Single-file scripts with no external dependencies need 'javac Main.java && java Main' — that's it. Maven earns its complexity when you have external dependencies that need resolution, multiple modules that depend on each other, or a team that needs consistent and reproducible builds. The rule of thumb: if your project doesn't have a pom.xml with at least one <dependency> block or at least two developers, Maven is probably adding cost without adding value.

✕Not understanding Maven lifecycle ordering

Symptom

A developer runs 'mvn deploy' expecting only artifact upload and is surprised by a 12-minute build that compiles, runs the full test suite, packages, and verifies before uploading. Or they run 'mvn package' during a tight deadline and can't understand why tests are executing when they just wanted the JAR. They add arbitrary flags from Stack Overflow without understanding which phase is the actual bottleneck.

Fix

Internalize the default lifecycle phase order: validate → initialize → generate-sources → process-sources → generate-resources → process-resources → compile → process-classes → generate-test-sources → process-test-sources → generate-test-resources → process-test-resources → test-compile → process-test-classes → test → prepare-package → package → pre-integration-test → integration-test → post-integration-test → verify → install → deploy. Every phase triggers all preceding phases. To skip test execution (not compilation) use -DskipTests. To skip test compilation and execution use -Dmaven.test.skip=true. Understand the difference before using either in production CI.

✕Ignoring warnings in Maven build output

Symptom

The build output contains several lines marked [WARNING] — non-thread-safe plugin configurations, deprecated API usage, SSL certificate issues during artifact download, or 'overriding managed version' notices for dependencies. The developer ignores them because the build still produces a [BUILD SUCCESS]. Six months later, the SSL certificate expires and the build fails completely. Or a deprecated API is removed in the next major version and the project is stranded on an old plugin version.

Fix

Treat every Maven [WARNING] line as a future [ERROR] with an unknown activation date. SSL warnings require importing the repository certificate into the JDK trust store — this is a one-time fix that takes ten minutes and prevents a future production incident. Deprecated API warnings should be resolved in the next sprint, not deferred indefinitely. Version override warnings ('overriding managed version X with Y') indicate a dependency conflict that should be resolved explicitly rather than silently overridden.

✕Hardcoding local file system paths in pom.xml

Symptom

A developer needs to include a custom JAR that isn't in any Maven repository. They add a <dependency> with <scope>system</scope> and a <systemPath> pointing to C:\Users\jdoe\libs\custom-sdk-1.0.jar. The build works perfectly on their machine. Every other developer, the CI server, and the staging deployment agent all fail with 'Artifact has no file.' The developer's reaction: 'It works on my machine' — which is precisely the problem Maven was designed to eliminate.

Fix

The correct solution for a JAR that isn't in a public repository is to install it to a repository. If your organization has Nexus or Artifactory, deploy it there and declare it as a normal dependency with GAV coordinates. If that's not available, install it to the local repository on every machine using 'mvn install:install-file -Dfile=custom-sdk-1.0.jar -DgroupId=com.vendor -DartifactId=custom-sdk -Dversion=1.0 -Dpackaging=jar' and document this setup step. As a last resort, commit the JAR to a project-local Maven repository structure and declare a <repository> pointing to a relative path — at least that path will be consistent across machines.

✕Using SNAPSHOT dependencies in production or release branches

Symptom

The CI pipeline has been green for two weeks. No code changes were committed overnight, but this morning's build fails with ClassNotFoundException for a class that was present yesterday. The dependency is declared as '2.3-SNAPSHOT'. The upstream team published a new snapshot build at 3am with a breaking API change, and Maven pulled it automatically. The downstream team spends half a day investigating a problem that wasn't caused by any code they wrote.

Fix

On any branch that produces a release artifact — main, release/, hotfix/ — disable SNAPSHOT resolution entirely in your Maven profile. Add a <repository> configuration with <snapshots><enabled>false</enabled></snapshots> to your release profile. This makes Maven refuse to resolve SNAPSHOT dependencies and will fail the build immediately if any are declared, rather than silently pulling an unstable artifact. For development branches, SNAPSHOT dependencies are acceptable but should be documented as temporary — a SNAPSHOT dependency that survives more than one sprint is a dependency that should have been pinned.

✕Not using dependencyManagement in multi-module projects

Symptom

A project has twelve modules. Three of them declare commons-lang3 at version 3.12.0, two declare it at 3.14.0, and one uses 3.9.0 because someone copied a pom.xml template from an old project. Maven's nearest-definition rule resolves to different versions in different modules depending on the transitive dependency graph. The production build works because the JVM happens to load a compatible version. The staging environment, with a slightly different classpath ordering, throws NoSuchMethodError. Reproducing the staging failure locally is nearly impossible.

Fix

Declare all shared dependency versions in the parent POM's <dependencyManagement> section. Child modules declare the <groupId> and <artifactId> without a <version> tag — they inherit the version from the parent's managed section. This is not the same as declaring the dependency in the parent's <dependencies> section (which would force every child to have that dependency). <dependencyManagement> only sets the version used when a child chooses to declare the dependency. The result: one place to update a version, consistent resolution across all modules, and a single diff in code review when you upgrade a library.

Interview Questions on This Topic

QWhat is the Project Object Model (POM) and why is it considered the 'unit of work' in Maven?JuniorReveal
The POM — the pom.xml file — is an XML descriptor that fully defines a Maven project: its GAV coordinates (GroupId, ArtifactId, Version), its dependencies with scopes and versions, its build plugin configuration, and inherited metadata from any parent POM. It is the 'unit of work' because every Maven command begins and ends with the POM. When you invoke 'mvn compile', Maven reads the POM to determine which source directories to scan, which dependencies to put on the compile classpath, which compiler plugin version and configuration to use, and what the output directory should be. Nothing in the build happens without Maven consulting the POM. The POM is declarative, not procedural. It says 'this project needs commons-lang3 version 3.14.0' — it doesn't say how to download it, where to store it, or how to add it to the classpath. That's Maven's job. This declarative nature is what makes pom.xml readable and auditable by people who haven't run the build, and it's what allows different tools — IDEs, CI servers, local Maven installations — to all interpret the same project consistently. One subtlety worth mentioning: every pom.xml silently inherits from the Super POM, Maven's built-in default descriptor. This is why a minimal pom.xml with only GAV coordinates can still run a complete compile-test-package cycle — the Super POM provides all the default plugin bindings and repository configuration.
QCan you explain the difference between 'mvn install' and 'mvn package'? When would you use one over the other?JuniorReveal
Both commands execute the same sequence of phases through the default lifecycle: validate, compile, test, package. The difference is what happens after the package phase. 'mvn package' stops after producing the artifact in the target/ directory — a JAR, WAR, or whatever the <packaging> type specifies. The artifact is available on the local filesystem but not installed anywhere Maven can resolve it as a dependency. 'mvn install' goes further: after packaging, it copies the artifact into the local Maven repository at ~/.m2/repository, organized by GAV coordinates. Once installed, other projects on the same machine can declare this artifact as a dependency in their pom.xml and Maven will resolve it locally without going to a remote repository. In practice: use 'mvn package' when you need the artifact for deployment, container packaging, or manual testing. Use 'mvn install' in multi-module projects where sibling modules need to depend on each other — you install the upstream module so the downstream module can resolve it. In CI/CD, 'mvn deploy' is the appropriate phase: it does everything install does and then uploads the artifact to a remote repository (Nexus, Artifactory) where the rest of the team and other build systems can access it. One common misuse: developers sometimes run 'mvn install' out of habit when 'mvn package' would suffice. This isn't harmful, but it populates the local repository with artifacts from every branch and every snapshot iteration, which can mask dependency issues that a clean resolution from remote would catch.
QWhat is the 'Convention over Configuration' philosophy and how does it benefit a large engineering team?Mid-levelReveal
Convention over Configuration means the build tool makes opinionated default decisions so you don't have to configure everything explicitly. In Maven specifically: source code lives in src/main/java, tests live in src/test/java, resources live in src/main/resources, compiled output goes to target/. If you follow these conventions, your pom.xml only needs GAV coordinates and dependency declarations — Maven handles the rest through the Super POM's defaults. For an individual developer this saves setup time. For a large engineering team the benefits compound significantly. First, navigability: a developer joining a team of 50 engineers who has worked with Maven before knows exactly where to find source code, tests, and configuration in any of the team's projects on their first day. There's no per-project README archaeology. Second, CI/CD standardization: build pipeline configuration is identical across all Maven projects. Jenkins or GitHub Actions uses the same 'mvn clean install' command for every project — no custom per-project build scripts. Third, tooling compatibility: IDEs, static analysis tools, coverage reporters, and code quality gates all understand the Maven standard layout and integrate without project-specific configuration. The cost is that breaking convention has a multiplier effect. When one team overrides defaults in pom.xml for a legitimate reason, that exception must be documented, understood by everyone who touches the project, and handled specially by every tool in the pipeline. The convention's value is directly proportional to how consistently it's followed across the organization.
QHow does Maven handle transitive dependencies and what is 'Dependency Mediation'?Mid-levelReveal
A transitive dependency is any dependency of your dependencies. If your pom.xml declares a dependency on Library A, and Library A's pom.xml declares a dependency on Library B, then Library B is a transitive dependency that Maven automatically includes on your classpath — you never declare it yourself. Dependency Mediation is Maven's algorithm for resolving version conflicts when multiple transitive paths pull in different versions of the same artifact. Maven uses the 'nearest definition wins' rule: whichever version is declared closest to your project in the dependency graph is the version that gets used. If your pom.xml explicitly declares version 2.0 of a library, that declaration is at depth 1. A transitive dependency that requires version 1.5 of the same library is at depth 2 or greater — your version 2.0 wins. If two transitive dependencies at equal depth both require different versions, the first one declared in your pom.xml wins. This has practical implications. First, you can override any transitive version by declaring it explicitly in your own pom.xml — just be aware you're taking responsibility for compatibility. Second, the winning version might not satisfy all consumers — if version 2.0 removed methods that version 1.5 code calls, you'll get NoSuchMethodError at runtime. Third, the verbose output of 'mvn dependency:tree -Dverbose' shows you exactly which version won for each dependency and which versions were omitted and why — this is the primary diagnostic tool for classpath conflicts. For multi-module projects, the correct approach to version management is <dependencyManagement> in the parent POM, which lets you declare authoritative versions for any dependency used across modules without forcing every module to declare that dependency.
QWhat are GAV coordinates (GroupId, ArtifactId, Version) and why must they be unique in a repository?JuniorReveal
GAV coordinates are Maven's addressing system — a three-part identifier that uniquely locates any artifact in the Maven ecosystem. GroupId identifies the organization or logical project group, following the reverse-domain convention that mirrors Java package naming (e.g., io.thecodeforge, org.apache.commons, com.google.guava). ArtifactId identifies the specific module or library within that group (e.g., forge-starter-app, commons-lang3, guava). Version identifies the specific release (e.g., 1.0.0, 3.14.0, 33.0.0-jre, 1.0-SNAPSHOT). They must be globally unique because Maven uses GAV coordinates as a file system path in repositories. The artifact io.thecodeforge:forge-starter-app:1.0.0 is stored at the path /io/thecodeforge/forge-starter-app/1.0.0/forge-starter-app-1.0.0.jar in any repository — local, remote, or proxy. If two different artifacts share the same GAV, one overwrites the other at that path. Every project that depends on those coordinates gets whichever artifact was published last, with no warning and no mechanism to detect the collision. The reverse-domain GroupId convention exists specifically to prevent namespace collisions between organizations. Apache Commons uses org.apache.commons. Google's Guava uses com.google.guava. These namespaces are controlled by their respective domain owners, so conflicts are structurally impossible between legitimate open-source projects. For internal libraries, using your organization's domain (reversed) ensures your internal artifacts have a namespace that doesn't conflict with anything on Maven Central.
QExplain the three standard lifecycles in Maven: default, clean, and site.Mid-levelReveal
Maven defines three independent lifecycles, each a sequence of ordered phases. They are independent in the sense that executing one lifecycle does not automatically trigger another — you must invoke them explicitly, often by passing multiple lifecycle names to a single mvn command. The default lifecycle handles the main build and deployment work. Its phases, in order, are: validate (verify the project structure and POM are correct), compile (compile source code), test (run unit tests using the compiled sources), package (bundle compiled code into a distributable format — JAR, WAR, etc.), verify (run integration tests and quality checks on the package), install (copy the package to the local repository), and deploy (upload the package to a remote repository). Running any phase executes all preceding phases in the sequence — 'mvn deploy' runs everything from validate through install before uploading. The clean lifecycle handles output directory removal. Its phases are pre-clean, clean, and post-clean. 'mvn clean' deletes the target/ directory. In practice, 'mvn clean install' is one of the most commonly used command combinations because it ensures a fresh compilation rather than incrementally compiling on top of potentially stale .class files. The site lifecycle generates project documentation. Its phases are pre-site, site, post-site, and site-deploy. 'mvn site' generates an HTML documentation site from POM metadata, Javadoc, test coverage reports, and dependency information. 'mvn site-deploy' uploads the generated site to a web server. The site lifecycle is used far less frequently than the other two in modern development, where documentation is often generated separately as part of a documentation platform.
QWhat is the difference between a Plugin and a Goal in Maven?Mid-levelReveal
A Maven plugin is a JAR file that packages one or more executable tasks — those tasks are called goals. The plugin is the container; the goal is the unit of work. For example, the maven-compiler-plugin is a plugin. It contains two primary goals: compiler:compile, which compiles the main source code, and compiler:testCompile, which compiles the test source code. The maven-surefire-plugin is another plugin, containing the surefire:test goal that discovers and runs unit tests. The maven-jar-plugin contains jar:jar, which packages compiled classes into a JAR file. Plugins are declared and configured in the <build><plugins> section of pom.xml. Goals are what get executed during a build. Maven binds specific goals to specific lifecycle phases automatically — this is called phase-to-goal binding. The compiler:compile goal is bound to the compile phase, compiler:testCompile is bound to the test-compile phase, surefire:test is bound to the test phase. When you run 'mvn compile', Maven executes the compiler:compile goal because it's bound to that phase. You can also invoke a goal directly without triggering the lifecycle: 'mvn compiler:compile' runs only that goal without running validate or any other preceding phase. The syntax is always plugin-prefix:goal-name. This is useful for running specific plugin functionality like 'mvn dependency:tree' or 'mvn help:effective-pom' — goals that produce diagnostic output rather than build artifacts. Understanding this distinction is important when adding custom plugin executions to pom.xml, because you're always configuring a specific goal within a plugin, not the plugin as a whole.

Frequently Asked Questions

What happens if I don't follow the standard folder structure?

Maven will not find your source code or test files — but it won't tell you that clearly. The build will appear to succeed, producing an empty or incomplete JAR. You can override the default source directories in the <build> section of pom.xml using <sourceDirectory> and <testSourceDirectory>, but this defeats the purpose of having a convention. Every tool that integrates with Maven — IDEs, CI pipelines, code analysis tools — expects the standard layout. Deviating means configuring each of those tools individually to understand your custom structure. The overhead accumulates quickly.

What is a 'Transitive Dependency'?

If your project depends on Library A, and Library A depends on Library B, then Library B is a transitive dependency of your project. Maven resolves and downloads it automatically — you don't declare it in your pom.xml. This is one of Maven's most significant quality-of-life features: before centralized dependency management, you had to manually track and download every library that every library you used also needed. The risk is that transitive dependencies can introduce version conflicts when two different libraries require different versions of the same transitive artifact. 'mvn dependency:tree' shows you the full resolved graph including all transitive dependencies.

What is the difference between a Local and Central Repository?

The local repository is a directory on your own machine — typically ~/.m2/repository on Linux and macOS, or C:\Users\<username>\.m2\repository on Windows. When Maven downloads an artifact from a remote repository, it stores it in the local repository and uses that cached copy for subsequent builds. You can also install your own artifacts there with 'mvn install'.

The Central Repository — repo1.maven.org — is a public server maintained by Sonatype and the Maven community. It hosts hundreds of thousands of open-source libraries. It is Maven's default remote repository, configured in the Super POM. Most organizations also run a private repository (Nexus or Artifactory) that proxies Central and hosts internal artifacts. In that setup, Maven is configured to resolve from the internal proxy, which caches Central artifacts and adds internal libraries.

What is the Super POM and why does it matter?

The Super POM is Maven's built-in default project descriptor that every pom.xml implicitly inherits from, whether you declare a <parent> or not. It defines the default directory structure (src/main/java, src/test/java, src/main/resources), default plugin versions bound to lifecycle phases (maven-compiler-plugin, maven-surefire-plugin, maven-jar-plugin, and others), and Maven Central as the default artifact repository.

It matters because it explains behavior you didn't configure. When you run 'mvn compile' on a minimal pom.xml with only GAV coordinates and it works, that's the Super POM providing the compiler plugin binding. When tests run automatically during 'mvn package', that's the Super POM binding Surefire to the test phase.

To see exactly what you're inheriting, run 'mvn help:effective-pom'. The output is the fully resolved POM — your pom.xml merged with all parent POMs and the Super POM. This command is invaluable when debugging unexpected build behavior, because the effective POM shows you every configuration value in play, including ones you never wrote.

How do I exclude a transitive dependency that's causing a conflict?

Add an <exclusions> block inside the specific <dependency> declaration that's pulling in the conflicting transitive dependency. Inside <exclusions>, add one <exclusion> with the <groupId> and <artifactId> of the transitive dependency you want to remove. Maven will resolve all other transitive dependencies from that parent normally but skip the excluded one.

Before using exclusions, run 'mvn dependency:tree -Dverbose' and confirm which dependency path is pulling in the conflicting version. Exclusions remove a dependency from a specific path in the graph — if the same artifact is being pulled in transitively via multiple paths, you may need exclusions in multiple places.

For broader version enforcement across a multi-module project, prefer <dependencyManagement> in the parent POM. This lets you declare the correct version once, and Maven will use that version wherever the dependency appears in the graph without removing it. <dependencyManagement> is version enforcement; <exclusions> is dependency removal. Use the right tool for the actual problem.

When should I use Maven profiles and what are the risks?

Maven profiles allow you to define sets of configuration overrides — dependencies, plugin configurations, properties — that activate under specific conditions: a particular environment variable is set, a JDK version is detected, or a profile is explicitly named on the command line with -P.

The legitimate use cases are narrow: activating different build behaviors for dev versus production environments (different database drivers, different packaging targets), enabling integration tests that are too slow for the default build, or handling platform-specific compilation requirements.

The risk is that profiles hide complexity. A build that behaves differently depending on which profile is active is harder to reason about and harder to debug — especially when a profile activates automatically based on an environment variable that exists on some machines but not others. I've seen teams where no one was certain which profile was active on CI, leading to builds that produced different artifacts in different environments without anyone realizing it.

Rule: always run 'mvn help:active-profiles' when a build behaves unexpectedly. It shows you exactly which profiles are active and why. Prefer explicit profile activation (-P profilename) over automatic activation based on environment detection whenever possible.

🔥

Naren Founder & Author

Developer and founder of TheCodeForge. I built this site because I was tired of tutorials that explain what to type without explaining why it works. Every article here is written to make concepts actually click.

About Naren Get in touch

Forged with 🔥 at TheCodeForge.io — Where Developers Are Forged