How to verify:

Run the following command on the agent-installed machine to check the Java version used by your application:

java -version

Requirements:

• JDK/JRE 1.6 to 24 is supported
• Agent v7.x requires Java 8+. For Java 5–7, use legacy agent v5.5.

Resolution (if Java version is not supported):

1. Upgrade to a supported Java version, or
2. Use a compatible legacy agent version (v5.5 for Java 5–7)

Outbound communication from the agent-installed machine to the Applications Manager (Host and Port) should be allowed — either directly or via a proxy.

How to verify:

1. From the Applications Manager server, navigate to Settings → Tools → Support → Installation Information to get the Web Server Port & SSL Port.

2. Ensure the same host & port is configured in apm.host of apminsight.conf.

3. Open the configured apm.host URL in a browser on the agent-installed machine and confirm it loads.

4. Run the below connectivity check command from the agent-installed machine:

Linux:

curl -ks http://<hostname>:<port>/index.do | grep -i 'Applications Manager'

Note: Replace http://<hostname>:<port> with the actual apm.host value from apminsight.conf (e.g., https://appmanager.example.com:8443). Use https:// if SSL is enabled, otherwise http://.

Windows (PowerShell as Administrator):

add-type 'using System.Net;using System.Security.Cryptography.X509Certificates;public class TrustAllCertsPolicy : ICertificatePolicy {public bool CheckValidationResult(ServicePoint a,X509Certificate b,WebRequest c,int d){return true;}}';[System.Net.ServicePointManager]::CertificatePolicy=New-Object TrustAllCertsPolicy;(Invoke-WebRequest -Uri 'http://<hostname>:<port>/index.do').Content -split "`n" | Where-Object {$_ -match 'Applications Manager'}

Note: Replace http://<hostname>:<port> with the actual apm.host value from apminsight.conf (e.g., https://appmanager.example.com:8443). Use https:// if SSL is enabled, otherwise http://.

Verify the output contains the text “Applications Manager”.

5. If the output does NOT contain “Applications Manager”, the configured endpoint is incorrect or network/firewall is blocking communication.

Resolution:

1. Ensure the correct endpoint (apm.host) is configured in apminsight.conf.
2. Ensure the network and firewall configuration allows communication from the agent-installed machine to Applications Manager.
3. If a proxy is used, configure proxy settings in apminsight.conf:

   behind.proxy=true
   proxy.server.host=proxyserver
   proxy.server.port=proxyport
   proxy.auth.username=proxyuser
   proxy.auth.password=proxypassword

4. After updating the settings, restart the application for the changes to take effect.

How to verify:

1. Identify the user account running your application server process:
   • Linux: ps -ef | grep java — note the user in the first column.
   • Windows: Open Task Manager → Details tab → locate your Java process (e.g., java.exe, tomcat9.exe) → note the “User name” column.
2. Verify the application user has read & write permissions on the agent directory:
   • Linux: ls -la <agent_directory>
   • Windows: Right-click agent folder → Properties → Security → check permissions for the application user.

Resolution:

1. Linux: chown -R <app_user>:<app_group> <agent_directory>
2. Windows: Right-click agent folder → Properties → Security → Edit → Add → [User Name] → Allow Read & Write permissions.
3. Restart the application and check.

Running multiple bytecode instrumentation agents simultaneously can cause JVM instability, especially during WAR deployments.

How to verify:

Check if other APM agents are loaded in the JVM:

• From process arguments (Linux):
  ps -ef | grep java | grep -i "javaagent\|agentpath"
• From process arguments (Windows PowerShell):
  Get-WmiObject Win32_Process -Filter "name='java.exe'" | Select-Object CommandLine | Format-List
• From agent startup log: Check apminsight_startup_*.log for Java Arguments line and look for other agent entries.

Sample startup log showing competing agent (Dynatrace):

[02 Mar 2026 15:53:29.327][apminsight-services-starter][INFO]: Java Arguments: [..., -javaagent:/opt/apminsight-agent/apminsight-javaagent.jar, -Dapminsight.agent.server.port=8080, ..., -agentpath:/opt/dynatrace/oneagent/agent/lib64/liboneagentloader.so=loglevelcon=none,...]

In the above log, both -javaagent (APM Insight) and -agentpath (Dynatrace) are loaded — this will cause conflicts.

Look for other -javaagent: or -agentpath: entries pointing to agents like Dynatrace, AppDynamics, Glowroot, New Relic, etc.

Resolution:

1. Remove or disable the competing agent’s -javaagent / -agentpath argument from the application server startup configuration.
2. Restart the application server.
3. Validate stability before proceeding with APM Insight agent installation.

When monitoring multiple Java applications on the same server, each JVM instance must have a separate agent directory to avoid configuration file corruption.

How to verify:

• Check if multiple -javaagent arguments across different JVMs point to the same agent directory.
• If apminsight.conf appears empty or truncated, this is likely the cause.

Resolution: Use -Dapminsight.home=<path> to specify a unique directory per instance. Refer to Section 4.3 for detailed steps.

1. In Applications Manager: APM → Add New Monitor → Java
2. Choose deployment type (Host/Container), OS (Windows/Linux), and Java framework
3. Enter application name, port, and Java version
4. Verify the Applications Manager URL is reachable. Edit if needed.
5. Execute the displayed command in Administrator terminal:
   • Windows: PowerShell (Run as Administrator)
   • Linux: Terminal with sudo/root
6. Follow framework-specific steps shown in UI to add -javaagent
7. Restart your application (mandatory)
8. Perform transactions to start seeing data

1. Download apminsight-javaagent.zip from Applications Manager
2. Extract to your application server. Contents:
   • apminsight-javaagent.jar — the agent
   • apminsight-javaagent-api.jar — API for custom instrumentation
   • apminsight.conf — configuration file
3. Edit apminsight.conf with required keys:

license.key=<YOUR_LICENSE_KEY>
apm.host=https://<AppManager_Host>:<Port>
application.name=<Your_Application_Name>
agent.server.port=<App_Running_Port>

apm.host=https://primary:8443, https://secondary:8443

4. Add -javaagent argument (see Server-Specific Installation Links below or Installation Help)
5. Restart your application

How to confirm:

Check apminsight_startup_*.log for the following log patterns:

[24 Jan 2026 10:52:15.320][apminsight-services-starter][WARN]: Connection to https://<host>:<port> has failed
[24 Jan 2026 10:52:15.325][apminsight-services-starter][ERROR]: Exception in Connect. Will try to reconnect after X minute(s).
java.lang.RuntimeException: All endpoints failed, agent dropping request

Resolution:

1. Verify the correct Applications Manager port: From the Applications Manager server, navigate to Settings → Tools → Support → Installation Information to get the Web Server Port & SSL Port.
2. Verify the same host & port is configured in apm.host of apminsight.conf.
3. Open the configured apm.host URL in a browser on the agent-installed machine and confirm it loads.
4. Run the connectivity check command:
   • Linux: curl -ks http://<hostname>:<port>/index.do | grep -i 'Applications Manager'
   • Windows (PowerShell as Administrator):
   add-type 'using System.Net;using System.Security.Cryptography.X509Certificates;public class TrustAllCertsPolicy : ICertificatePolicy {public bool CheckValidationResult(ServicePoint a,X509Certificate b,WebRequest c,int d){return true;}}';[System.Net.ServicePointManager]::CertificatePolicy=New-Object TrustAllCertsPolicy;(Invoke-WebRequest -Uri 'http://<hostname>:<port>/index.do').Content -split "`n" | Where-Object {$_ -match 'Applications Manager'}

   Note: Replace http://<hostname>:<port> with the actual apm.host value from apminsight.conf (e.g., https://appmanager.example.com:8443). Use https:// if SSL is enabled, otherwise http://.

   Verify the output contains the text “Applications Manager”. If not, the configured endpoint is incorrect or network/firewall is blocking communication.

5. Check firewall rules, DNS resolution, port availability.
6. If proxy required, configure in apminsight.conf:

   behind.proxy=true
   proxy.server.host=proxyserver
   proxy.server.port=proxyport
   proxy.auth.username=proxyuser
   proxy.auth.password=proxypassword

7. Restart application.

How to confirm:

Check apminsight_startup_*.log for the following log pattern:

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 901(Invalid agent.)
java.lang.RuntimeException: Agent didnot receive instance-id from server.

Cause: The license.key configured in apminsight.conf does not match the Applications Manager configured in apm.host. Sometimes users configure a different Applications Manager’s license key instead of the one matching the configured apm.host.

Resolution:

1. Login to the Applications Manager configured in apm.host.
2. Go to: APM → Add New Monitor → Java
3. On the right-side panel, find the APM Insight license key section.
4. Click the copy icon next to the license key to copy it.
5. Update license.key in apminsight.conf with the copied key.
6. Restart application.

Critical Issue: This is one of the most common onboarding failures!

How to confirm:

• apminsight.conf is empty or truncated.
• Multiple JVMs start simultaneously referencing same agent directory.
• All instances fail with “license.key is invalid”.
• Multiple microservices show as the same instance, or port does not match the configured -Dapminsight.agent.server.port.

Cause: Concurrent file access from multiple JVM processes corrupts the conf file. The agent groups instances by directory — services sharing the same directory appear as the same instance.

Resolution: Each instance must have its own agent directory. Use -Dapminsight.home along with JVM system property overrides to point each JVM to its own directory:

-javaagent:/opt/apminsight-agent/apminsight-javaagent.jar
-Dapminsight.home=/opt/apminsight-agent/<application_name>
-Dapminsight.application.name=<application_name>
-Dapminsight.agent.server.port=<application_running_port>
-Dapminsight.license.key=<your_apminsight_license_key>
-Dapminsight.apm.host=<applications_manager_url>

🔗 KB: Monitor Multiple Applications on Single Server

How to confirm:

Check apminsight_startup_*.log for the following log pattern:

[24 Jan 2026 10:52:15.450][apminsight-services-starter][WARN]: SSL handshake failed for <host>: Unsupported curveId: 29

Cause: Old Java 8 version lacks Curve25519 support.

Resolution (choose one):

1. Option A: Add JVM argument:

   -Djdk.tls.namedGroups="secp256r1,secp384r1,secp521r1"

2. Option B: Upgrade JVM to Java 11+
3. Option C: Downgrade agent to v7.4 (Upgrade/Downgrade steps)

How to confirm:

• Application server stops unexpectedly or WAR deployments fail/hang.
• Check for multiple -javaagent or -agentpath arguments in the running process:

Linux:

ps -ef | grep java | grep -i "javaagent\|agentpath"

Windows (PowerShell):

Get-WmiObject Win32_Process -Filter "name='java.exe'" | Select-Object CommandLine | Format-List

Also check apminsight_startup_*.log for the Java Arguments line:

[02 Mar 2026 15:53:29.327][apminsight-services-starter][INFO]: Java Arguments: [..., -javaagent:/opt/apminsight-agent/apminsight-javaagent.jar, -Dapminsight.agent.server.port=8080, ..., -agentpath:/opt/dynatrace/oneagent/agent/lib64/liboneagentloader.so=loglevelcon=none,...]

In the above log, both -javaagent (APM Insight) and -agentpath (Dynatrace) are loaded simultaneously — this confirms the conflict.

Look for other agent JARs like Dynatrace (-agentpath:...liboneagentloader...), AppDynamics (-javaagent:...javaagent.jar), Glowroot (-javaagent:...glowroot...), New Relic, etc.

Cause: Multiple bytecode agents cause class transformation conflicts.

Resolution:

1. Remove or disable the competing agent’s -javaagent / -agentpath argument from the application server startup configuration.
2. Restart application server.
3. Validate stability before re-enabling.

How to confirm:

1. Check startup log exists: apminsight_startup_<timestamp>_<PID>.log
   • Look for: APM Insight javaagent v7.x.x.x successfully hooked up with JVM
2. If no startup log: The -javaagent argument was not applied.
   • Check correct config file for OS (see Section 5).
   • Verify JAR path is correct.
   • Confirm application was actually restarted (not just reloaded).
3. If startup log exists with errors: Check connection and response codes in the log.

Resolution:

1. Ensure the -javaagent argument is correctly placed in the appropriate configuration file for your application server.
2. Fully restart (not reload) the application server.
3. Generate some application traffic (transactions/requests) for the agent to detect.
4. Check the startup log for connection errors or response codes and refer to the relevant troubleshooting section.

How to confirm:

Check apminsight_startup_*.log for the following log pattern:

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 701(License expired. Kindly update license!)

Cause: The “APM Insight Java Add-On” license has expired or the add-on license is not enabled on the Applications Manager.

Resolution:

1. Apply & ensure the “APM Insight Java Add-On” licensing is enabled on the Applications Manager.
2. Navigate to APM → Add New Monitor → Java and verify the license status.
3. After license renewal, the agent auto-recovers within the 15-day grace period (no restart needed).
4. If the grace period has passed, restart the application to reconnect.

How to confirm:

Check the application server log (server.log) for:

ERROR [stderr] java.lang.NoClassDefFoundError: com/manageengine/apminsight/agent/JavaAgent

Cause: Missing or duplicate -Djboss.modules.system.pkgs argument. For Liferay DXP on JBoss, the OSGi container additionally requires boot delegation configuration.

Resolution:

Step 1: Consolidate into a single -Djboss.modules.system.pkgs argument:

-Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine

Correct file by OS:

Step 2 (Liferay DXP on JBoss only): If NoClassDefFoundError persists even after Step 1, Liferay’s OSGi container needs boot delegation configuration. Add to portal-ext.properties:

module.framework.properties.org.osgi.framework.bootdelegation=<existing-values>,com.manageengine.*

Then restart application server.

🔗 Help: JBoss EAP Installation | 🔗 External: Liferay Java Agents

How to confirm:

Adding agent via Management Console can cause startup failures because existing JVM args get overridden.

Resolution: For domain mode, always edit host.xml directly:

• <JBOSS_HOME>/domain/configuration/host.xml
• Add -javaagent under <jvm-options> for required server groups
• This allows selective restarts (only affected domains/hosts)

🔗 Help: JBoss EAP Installation

How to confirm:

Agent added to standalone.conf but no apminsight_startup_*.log is created on Windows.

Cause: Windows uses standalone.conf.bat, not standalone.conf.

Resolution: Use the correct file:

How to confirm:

Arguments added via WebLogic Console for Admin Server are not picked up. No apminsight_startup_*.log is created.

Cause: Admin Server startup overrides console-based arguments. The -javaagent option must be added directly in the startup script, after the setDomainEnv.sh call.

Resolution: Use a text editor and edit the startup script directly. Add the -javaagent option to JAVA_OPTIONS after the setDomainEnv call:

Linux: <DOMAIN_HOME>/bin/startWebLogic.sh

# Add AFTER the setDomainEnv.sh call:
JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:<path>/apminsight-javaagent.jar"

Windows: <DOMAIN_HOME>\bin\startWebLogic.cmd

@REM Add AFTER the setDomainEnv.cmd call:
set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:<path>\apminsight-javaagent.jar

🔗 Help: WebLogic Installation

How to confirm:

Spring Boot runs as Windows Service (via WinSW, procrun, etc.) and no apminsight_startup_*.log is created after adding -javaagent.

Resolution:

1. Locate the .bat or .xml file used for service registration.
2. Add -javaagent to JVM options in that file.
3. Unregister and re-register the Windows service.
4. Restart service.

🔗 Help: Spring Boot Installation

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 701(License expired. Kindly update license!)

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 702(Number of instances supported for this license exceeds the limit.)

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 901(Invalid agent.)
java.lang.RuntimeException: Agent didnot receive instance-id from server.

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 900(Delete the agent.)

[24 Jan 2026 10:53:53.695][apminsight-services-starter][INFO]: Collector Response Code: 910(Unmanage the agent.)
[24 Jan 2026 10:53:53.710][apminsight-services-starter][INFO]: Disabling monitoring for context '...'

[26 Feb 2026 15:50:39.609][apminsight-2-thread-2][INFO]: Collector Response Code: 911(Manage the agent.)
[26 Feb 2026 15:50:39.610][apminsight-2-thread-2][INFO]: 47 metric(s) dispatched for context ''. Context currently enabled:true