Comprehensive Guide to Remote Debugging in Maven Projects Using exec Plugin

Analysis of Debugging Requirements in Maven

During Maven project development, when programs exhibit unexpected hanging or abnormal behavior, traditional logging output often fails to precisely identify the root cause. In such cases, enabling Java debuggers (like jdb) for runtime state inspection becomes necessary. Users typically expect to directly initiate debugging sessions through commands similar to mvn exec:jdb, but Maven does not natively include such shortcuts.

Core Debugging Solution Implementation

The remote debugging configuration based on the Maven exec plugin currently represents the most reliable solution. By adjusting JVM startup parameters, JDWP (Java Debug Wire Protocol) debugging support can be enabled:

mvn exec:exec -Dexec.executable="java" -Dexec.args="-classpath %classpath -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044 com.mycompany.app.App"

This command implements debugging functionality through three key parameters: -Xdebug enables JVM debugging capabilities, -Xrunjdwp configures the debug transport protocol, where transport=dt_socket specifies socket communication, server=y sets the current process as debug server, suspend=n ensures immediate program execution without waiting for debugger connection, and address=1044 defines the debug port number.

Debugger Connection Configuration

After the Maven process begins listening for debug connections on port 1044, corresponding configuration is required on the debug client side. Taking Eclipse as an example:

1. Open the Debug Configurations dialog
2. Create a new Remote Java Application configuration
3. Set connection host as localhost and port as 1044
4. Select the corresponding project source code requiring debugging
5. Initiate the debug connection to begin interactive debugging sessions

Configuration processes for other mainstream IDEs (IntelliJ IDEA, NetBeans) are similar, all supporting connections to debug servers through the same protocol.

Parameter Optimization and Considerations

Debug parameters can be flexibly adjusted according to actual requirements:

• Port conflict resolution: When default ports are occupied, available ports can be switched by modifying the address parameter value (e.g., 1045)
• Startup control: Changing suspend=n to suspend=y can pause the program before debugger connection, facilitating initial breakpoint setup
• Classpath assurance: Ensure the %classpath variable correctly resolves project dependencies to avoid class not found errors

Cross-Platform Compatibility Considerations

In Unix/Linux systems, attention must be paid to differences in environment variables and path separators. Windows systems use semicolons for path separation while Unix systems use colons. Simultaneously ensure debug ports are open in firewall rules, particularly when debug clients and servers reside on different hosts.

Alternative Solution Comparison

Beyond the exec plugin solution, Maven provides other debugging approaches:

• mvnDebug command: Suitable for Maven 2.0.8+ versions, automatically enables debugging on port 8000, but lacks execution parameter customization capabilities
• Surefire plugin debugging: Test cases can be debugged through the -Dmaven.surefire.debug parameter, defaulting to port 5005
• Manual JVM parameter configuration: Directly modifying the MAVEN_OPTS variable in Maven startup scripts, but affects all Maven operations

Typical Issue Troubleshooting

Common problems during debugging include:

• Connection refused: Verify debug port is correctly listened to using netstat -an | grep 1044
• Source code mismatch: Ensure source code versions set in IDE match running versions
• Insufficient privileges: Non-privileged users cannot use ports below 1024 in Linux/Unix systems