Node.js Troubleshooting Framework Configuration

General Configuration Troubleshooting

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

  2. Run the Diagnostics CLI to collect data then validate:

    1. Confirm Node.js and NPM version meets requirements.
    2. Verify host information meets requirements.
    3. Verify the existence of newrelic module in the package.json/package-lock.json
    4. Check top level npm ls dependencies for newrelic module.
    5. Check if the newrelic.js file is copied to the root directory of the application as described in step 3 of our install documentation.
    6. Ensure configuration is valid with a license key and app name.
    7. Check for the existence of agent logs in default path.
    8. Check that agent can connect to the New Relic collector.
    9. Verify agent isn’t an EOL version.
    10. Check for a “reporting to” line in the logs.
    11. Check that High Security Mode settings for the application and account match.
  3. Look at the newrelic.js file and make sure the configuration options you want enabled are there and formatted correctly.

    1. While you are here, check that the exports line isexports.config = {... and NOT exports.config = () => ({... The latter is a function call and is usually there if the default.js was edited instead of copying and editing the base newrelic.js.
  4. Are you using Server Side Configuration settings? Anything set via SSC will override all other config options for the agent.

    1. Once enabled, SSC can only be disabled by support.
  5. If you used New Relic environment variables for configuration.

    1. Check where you store environment variables, such as in an .env file.

    2. command line: env | grep NEW_RELIC_ or printenv

    3. Use console.log(process.env) before require(newrelic); to make sure the env vars are correctly loading in time

    4. All Node agent New Relic ENV variables start with NEW_RELIC_, confirm these are set correctly.

    5. Every standard config option has an ENV variable option, except for these two: NEW_RELIC_NO_CONFIG and NEW_RELIC_HOME

      1. If NEW_RELIC_NO_CONFIG_FILE=true, make sure that you have all the required ENV variable configuration equivalents. Ex: app_name, license_key, etc.
      2. If NEW_RELIC_HOME is set, make sure that the newrelic.js file is in the path it specifies.
  6. Ensure you are using a supported Node.js framework.

  7. Look through trace logs and make sure the configuration is reaching New Relic.

    1. You’ll usually see the configuration settings in a giant log entry that follows a “Posting to” message.
  8. If you are using Lambda, review our Lambda documentation.

Advanced Configuration Troubleshooting

Docker Configuration

  1. Make sure you have installed the Node.js agent correctly in a Docker container
  2. Check your Dockerfile, package.json and the ENV variables you are using. Make sure they are aligned with the above doc.

Browser Injection Configuration

  1. Check to see if the browser snippet is being injected and showing in a pages source code by searching for NREUM. If not, check the console for errors mentioned in the docs.
  2. Ensure you have called newrelic.getBrowserTimingheader() at the beginning of your html page’s head tag.
  3. Check and make sure that your html template has access to the New Relic module. Examples can be found in our docs.
  4. Review Browser troubleshooting framework

Proxy Issues

  1. Check configuration for any proxy settings and ensure they are formatted correctly.
  2. Verify that you included https or http as required by your proxy. These need to be included or else there will be a connection issue.
  3. Try having the entire proxy under the proxy configuration value. Sometimes issues occur when a you uses the separate config options (usually because of formatting nuances).
  4. If the config options look normal then you will likely need to contact your network admin for more help.

Distributed Tracing/CAT

  1. The number one issue with DT is formatting the configuration option incorrectly in your newrelic.js. It needs to looks like this:
distributed_tracing: {

enabled: true,

  1. Ensure all applications that should communicate have DT enabled and are using the latest version of the agent.

Naming Rules

You can group your own transaction names using this config option. You must format the regex correctly and put the options in the correct order. Our docs have a good example of how to use this. Be mindful to not create a Metric Grouping Issue


  1. There’s a great explanation of attributes for the Node.js agent in our docs.
  2. Check the related EventType in Insights for the attribute to see if it exists and troubleshoot from there.