Avoid the Top 10 Maven Pitfalls That Break Your Builds

Introduction

Recently many people in Knowledge Planet ask me Maven questions. Maven is used frequently in daily development. This article summarizes the most common Maven pitfalls.

1. Maven Core Principles

1.1 Coordinate System

Coordinate conflict example:

<!-- 错误：同一artifactId声明两次 -->
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpclient</artifactId>
  <version>4.5.13</version>
</dependency>
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>httpclient</artifactId>
  <!-- 同名不同组！ -->
  <version>1.0.0</version>
</dependency>

Symptom: NoSuchMethodError appears randomly because the classloader loads the wrong JAR.

1.2 Dependency Transitivity

Dependency resolution process:

Propagation rules:

Shortest path wins : A→B→C→D(1.0) vs A→E→D(2.0) → choose D(2.0)

First declaration wins : the version declared first takes precedence.

1.3 Lifecycle

Key features:

Running mvn install automatically triggers all phases from validate to install.

Plugin binding: each phase is implemented by a specific plugin (e.g., compile phase bound to maven-compiler-plugin).

1.4 Repository System

Private repository core values:

Cache public dependencies → accelerate builds.

Host internal third‑party artifacts → security isolation.

Control dependency approval flow → compliance.

2. Most Common Maven Pitfalls

Pitfall 1: Circular Dependency

Case: order module depends on payment, payment depends on order.

Error: [ERROR] A cycle was detected in the dependency graph Solution:

Extract a common layer: order-api ← order-core & payment-core Apply Dependency Inversion (interface in payment, implementation in order).

// In payment module define interface
public interface PaymentService {
    void pay(Order order);
}

// order module implements the interface
public class OrderServiceImpl implements PaymentService {
    // implementation
}

Pitfall 2: Dependency Conflict

Typical scenario: Component A depends on C:1.0, component B depends on C:2.0 → Maven selects one version causing compatibility issues.

Diagnosis tool: mvn dependency:tree -Dverbose Output shows conflicting versions.

Force unified version:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
            <version>1.2</version> <!-- force version -->
        </dependency>
    </dependencies>
</dependencyManagement>

Pitfall 3: Snapshot Dependencies

Misconfiguration: using a 1.0‑SNAPSHOT version for production.

Risk: Same version number may point to different binaries, causing inconsistent behavior.

Guidelines:

Release builds must use a fixed version such as 1.0.0.

Internal integration may use SNAPSHOT but must be coupled with CI.

Pitfall 4: Wrong Dependency Scope

Wrong case: declaring javax.servlet-api with compile scope instead of provided.

Consequence: java.lang.ClassCastException at runtime because the container already provides the library.

Pitfall 5: Missing Resource Filtering

Problem: application.yml under src/main/resources contains placeholders that are not replaced.

Fix: enable filtering in pom.xml and define the property.

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
        </resource>
    </resources>
</build>

<properties>
    <DB_URL>jdbc:mysql://localhost:3306/test</DB_URL>
</properties>

Pitfall 6: Outdated Plugin Version

Classic case: using Maven Compiler Plugin 3.1 with JDK 17.

Error: Fatal error compiling: invalid target release: 17 Upgrade:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <source>17</source>
        <target>17</target>
    </configuration>
</plugin>

Pitfall 7: Multi‑module Build Order

Wrong structure: parent pom lists modules in an order where a dependent module is built before its dependency.

Build command: mvn clean install may fail.

Correct configuration: declare modules in dependency order.

<!-- parent pom declares build order -->
<modules>
    <module>order-service</module>
    <module>payment-service</module>
    <module>user-service</module>
</modules>

Pitfall 8: Local Repository Pollution

Failure scenario: mvn clean install succeeds locally but fails on a colleague because the local cache contains a corrupted lastUpdated file.

Cleanup:

# Remove all invalid files
find ~/.m2 -name "*.lastUpdated" -exec rm {} \;

# Force re‑download
mvn clean install -U

Pitfall 9: Private Repository Misconfiguration

Slow cause: direct access to central repository from China and incorrect mirror settings.

Optimized settings.xml :

<mirrors>
    <mirror>
        <id>aliyun</id>
        <name>Aliyun Maven Mirror</name>
        <url>https://maven.aliyun.com/repository/public</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
</mirrors>

Pitfall 10: IDE vs CLI Inconsistency

Typical divergence: Eclipse compiles successfully while command line fails due to mismatched .project and pom.xml; IDEA runs tests fine but CLI fails because test resources are not configured.

Unified solution:

<!-- Explicitly configure test resources -->
<testResources>
    <testResource>
        <directory>src/test/resources</directory>
        <filtering>true</filtering>
    </testResource>
</testResources>

3. Enterprise‑Level Best Practices

Dependency Management Golden Rules

Strict parent POM: lock all versions in <dependencyManagement>.

Continuous inspection: add dependency checks to CI pipelines (e.g., mvn versions:display-dependency-updates).

Separate public and private dependencies: public artifacts from a mirror, internal artifacts from a private repository.

High‑Availability Build Architecture

Conclusion

If it builds, mvn clean install will run.

Understanding the lifecycle and resolving conflicts makes you "use" Maven effectively.

Leverage tools such as mvn dependency:analyze, archetypes, and the enforcer‑plugin to keep builds clean.

Maven's essence is not a tool constraint but an architectural discipline.