Java Agent Troubleshooting Framework Install

Once you’ve installed the Java agent, you should see data reporting within a few minutes. If you’re having trouble, these are the steps that our support teams take to troubleshoot, and we hope they will help you find and resolve the issue quickly.

  1. Confirm the app is receiving traffic, has been for at least 5 min, and continues to receive traffic during troubleshooting

  2. Follow the troubleshooting steps at

  3. Confirm you application meets the Agent’s Compatibility and Requirements

  4. Run NrDiag

  5. Confirm configuration options

  6. Confirm Java process options, if a Java process is detected. Some versions of Java are not compatible with certain releases of our agent.

  7. Confirm there’s an agent log file

  8. Confirm OS, JDK/JRE version

  9. Confirm you are using the correct license key

  10. Verify the name of the application that should be reporting

  11. Check for High Security Mode configuration mismatches.

  12. Check application log for 2 lines branded with New Relic that tell which newrelic.yml file the configuration is being read from and to which file the logging information is being written

  13. Confirm the Java process includes the -javaagent parameter. We have some examples at Include the Java agent with a JVM argument but this is not an exhaustive list.

  14. The command-line ps -ef JavaProcess should work for UNIX/LINUX.

  15. For Windows there’s a myriad of tools: Task Manager, wmic, Powershell, Process Explorer

  16. The process could have a name given by the vendor such as Tomcat

  17. On Windows, the Java process could also be running as a service

  18. Check for the agent log. If there is no log, there’s a possibility that step 5 failed. Default location is in /logs under the location where the newrelic.jar file resides and the default file name is newrelic_agent.log

  19. If there is no file for step 3 above, check the newrelic.yml file for a configured file path log_file_path and log_file_name.

  20. Alternately, there could be -Dnewrelic.config.log_file_path= and -Dnewrelic.config.log_file_name= parameters in the JVM options

  21. Another option for setting config options is through Environment Variables

  22. Confirm you restarted the application to pick up the -javaagent command?

  23. If you are running on Windows, did you stop and restart the application?

  24. If you are running on Windows and the application is running as a Windows Service, did you update the Windows Service

  25. You may need to work with your internal teams for the above steps

There is a possibility with the various frameworks and embedded frameworks that are in COTS (Commercial Off The Shelf) software that the adding the -javaagent parameter could be hidden in a startup script, administrative console or even that the application comes up and spawns a new JVM instance that the parameters do not persist to so the agent just won’t get picked up that way.

Corner cases to keep in mind when troubleshooting:

  1. Some versions of Java use endorsed directories (-Djava.endorsed.dirs) but this was deprecated in more recent versions. If that option is set in the Java options, it means only the folders listed will be read by the JRE. If the agent is outside of the endorsed directories, it will be ignored even if it appears to be configured properly.

  2. If using Tableau Software, ensure you are not using a version that does not allow any updates to the JVM options hard-coded into their product. If this is the case you will need to work with Tableau or your internal teams to find a resolution.

  3. If another -javaagent is running in the JVM, it should still be okay in most circumstances but can cause issues. Sometimes swapping the order of the options so the New Relic agent loads first resolves these issues. If this does not resolve the issue it may be that the New Relic Agent and the other agent have a conflict of some type.

  4. If you are still unable to resolve the issue please reach out to New Relic Global Technical Support by going to Please be sure to mention, in as much detail as possible, the steps you have tried already and details of what you expect to see and what you are seeing.

1 Like