Understanding Agent entries in stack traces

When a Java application protected by the Waratek Agent throws an exception or logs a stack trace, you may see frames referencing internal package names such as replicode, oceanic, or waratek. This page explains what these entries mean and how to determine whether the Waratek Agent is related to the error.

Why the Waratek Agent appears in stack traces

The Waratek Agent monitors certain Java method calls at runtime to enforce security rules and detect vulnerabilities. To do this, the Agent adds lightweight intercept points around standard Java operations such as file access, network calls, SQL queries, and HTTP request handling.

When the JVM constructs a stack trace, it includes every method in the call chain — including the Agent's intercept points. This is normal and expected behavior for any Java agent that performs runtime security analysis. The presence of Agent frames in a stack trace does not, by itself, indicate that the Agent caused the error.

Common package names

The following internal package prefixes may appear in stack traces when the Waratek Agent is attached. Both replicode.* and oceanic.* may appear depending on the Agent version and configuration.

Package prefix	Description
replicode.core.trampolines	Security intercept points for standard Java operations
replicode.core.iast	Application security analysis
replicode.core.utils	Internal utility classes
replicode.core.accessors	Classes that inspect request and response data
replicode.core.recompiler	The Agent's class transformation engine
replicode.core.armr.patch	Virtual patch execution
oceanic.*	Agent core components

Does the Waratek Agent cause the error?

The key to reading a stack trace is identifying where the exception originates — the topmost frame in the trace. Agent frames appearing lower in the stack simply mean the Agent was part of the call chain, not that it caused the failure.

When the error is likely unrelated to the Waratek Agent

The error is most likely unrelated to the Agent when:

• The exception type is a standard application error (e.g. NullPointerException, SQLException, IOException) and the topmost frame is in your application or library code, not in Agent code.
• Agent frames (e.g. replicode.*, oceanic.*) appear in the middle or bottom of the stack trace, meaning the Agent was simply part of the call chain when the exception occurred.
• The same error also occurs when the application runs without the Agent attached.

When the error may be related to the Waratek Agent

The error may be related to the Agent when:

• The exception originates from a replicode.*, oceanic.*, or waratek.* frame — that is, the topmost frame in the stack trace belongs to one of these packages.
• The exception type references Agent-specific classes, such as oceanic.controller.ControllerException or replicode.core.recompiler.RecompilerError.
• The error only occurs when the Agent is attached and disappears when the Agent is removed.
• The error involves ClassNotFoundException or NoClassDefFoundError for Agent-internal classes (e.g. replicode.core.trampolines.*). This can indicate a classloader conflict, particularly in modular application servers like JBoss or WildFly.

What to do next

If the error appears unrelated to the Waratek Agent, investigate the application or library code indicated at the top of the stack trace. You can safely disregard the Agent frames in the middle of the trace — they are part of normal operation.

If the error appears related to the Waratek Agent, collect the following information and open a support ticket:

• The complete stack trace
• The Waratek Agent version
• The application server type and version
• The JDK vendor and version
• Any ARMR rules or patches that were active at the time

For debug logging options that may help diagnose the issue, see Troubleshooting and debugging options.

Example stack trace

In this example, a NullPointerException occurs in application code. The Waratek Agent frames appear in the stack because the Agent was monitoring the servlet request, but the Agent did not cause the error. The root cause is in the application's UserService.getProfile() method.

java.lang.NullPointerException: Cannot invoke "String.length()" because "name" is null
    at com.myapp.service.UserService.getProfile(UserService.java:47)          // <-- root cause
    at com.myapp.servlet.UserServlet.doGet(UserServlet.java:31)
    at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:564)
    at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:658)
    at replicode.core.trampolines.ServletTrampoline.service(ServletTrampoline.java:112)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:153)
    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:168)
    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:90)
    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:130)
    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:342)
    at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:390)
    at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:63)
    at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1739)
    at java.base/java.lang.Thread.run(Thread.java:833)

In this trace, replicode.core.trampolines.ServletTrampoline.service appears because the Agent monitors servlet requests. The actual error is in UserService.getProfile() at line 47, which is standard application code.