Build tools (Maven & Gradle)🔗

Build tools such as Maven and Gradle compile application code as part of the build process. In some cases, this process may exclude or transform debugging symbols and runtime artifacts in order to reduce binary size or optimize the output for distribution.

To ensure Lightrun can attach correctly and provide full debugging capabilities, specific build-time settings may be required. These settings do not affect application performance or optimizations, but ensure that the necessary symbols and runtime components remain accessible.

Maven🔗

Build the project🔗

Lightrun's agent needs to find several symbols, including your project's variables, so that later it would be possible to add actions.

In order to find those symbols, it is needed to add debug options to the Java compiler via Maven. Maven compiles with the maven-compiler-plugin, which can be configured in the <configuration> tag. Under that clause, in the <compilerArgs> tag, we will add -g which is the debugging information option for the Java compiler. To that we will append the keywords source, lines and vars . For more information, see Compiling Java for optimal debugging. Add the following lines to the pom.xml file:

<configuration>
  <compilerArgs>
    <arg>-g:source,lines,vars</arg>
  </compilerArgs>
</configuration>

The pom.xml file should match this structure after insertion:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
      <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>[...]</version>
        <configuration>
          <compilerArgs>
            <arg>-g:source,lines,vars</arg>
          </compilerArgs>
        </configuration>
      </plugin>
    </plugins>
    [...]
  </build>
  [...]
</project>

Run the project with Maven Wrapper🔗

Set the MAVEN_OPTS environment variable, in order to pass the Lightrun agent as a parameter to the JVM running Maven. From the server terminal, enter the following command (replace the agentpath value with the path to the Lightrun agent, after it has been downloaded):

MAVEN_OPTS=-agentpath:/path/to/agent/lightrun_agent.so ./mvnw

Important

Change /path/to/agent/ to the downloaded agent folder full path.( Note - using ~/ will not work)

Troubleshooting

Make sure that the JAVA_TOOL_OPTIONS environment variable is unset, otherwise it will interfere with the MAVEN_OPTS variable. You can check the value of JAVA_TOOL_OPTIONS with:
```
echo $JAVA_TOOL_OPTIONS
```
If the environment variable is assigned, backup the value if needed and then delete the variable with:
```
unset JAVA_TOOL_OPTIONS
```
Make sure that your mvnw file includes the MAVEN_OPTS environment variable when executing the project. If not, add it like so (usually in the last command in the file):
```
exec "$JAVACMD" \
$MAVEN_OPTS \
[...]
```

Gradle🔗

In the Gradle build file, ensure that the following properties are specified:

compileJava.options.debugOptions.debugLevel = "source,lines,vars"
compileTestJava.options.debugOptions.debugLevel = "source,lines,vars"

Last update: February 3, 2026