Troubleshooting

Start with the agent log. By default it is newrelic_agent.log in the process's working directory, at level info. For a problem you cannot explain, raise the level temporarily:

NEW_RELIC_LOG_LEVEL=trace NEW_RELIC_LOG=stdout node -r newrelic app.js

logging.level accepts fatal, error, warn, info, debug, and trace, plus the aliases verbose (→ trace), debugging (→ debug), warning (→ warn), and err (→ error). logging.filepath (NEW_RELIC_LOG) can be a path, stdout, or stderr.

Then validate the configuration:

npx newrelic validate-config -c ./newrelic.js

See newrelic validate-config.

The Agent Does Not Start

When the agent decides not to start, your application keeps running and require('newrelic') returns the stub API. Look for these messages:

Message (log or stderr) Cause Fix
New Relic for Node.js requires a version of Node >=22.16.0 ... Not starting! Node.js is too old. Upgrade Node.js, or stay on an older agent major version.
New Relic for Node.js is disabled due to an error: (on stderr) The configuration could not be built — usually a configuration file that fails schema validation. Run validate-config and fix the reported key.
Module disabled in configuration. Not starting. agent_enabled: false or NEW_RELIC_ENABLED=false. Re-enable it.
No configuration detected. Not starting. No configuration could be built at all. Check the file and environment variables.
New Relic requires that you name this application! No app_name (and not in serverless mode). Set app_name or NEW_RELIC_APP_NAME.
Not starting without license key! No license_key. Set license_key or NEW_RELIC_LICENSE_KEY.
New Relic for Node.js in worker_threads is not officially supported. Not starting! The agent was loaded inside a worker thread. Load it in the main thread only, or set worker_threads.enabled: true to bypass the check (unsupported).
OpenTelemetry bridge enabled, but packages are missing. Not starting! opentelemetry.enabled is true but the @opentelemetry/* dependencies cannot be resolved. Reinstall newrelic with its dependencies. See OpenTelemetry Bridge.

Under Agent Control, the same situations appear as health codes such as NR-APM-002 (license key missing) or NR-APM-005 (missing application name).

The Configuration File Is Ignored

Symptom Cause Fix
Settings from newrelic.js have no effect. The file is not where the agent looks (working directory, NEW_RELIC_HOME, HOME, the directory above node_modules, the main module's directory). Set NEW_RELIC_HOME to its directory, or NEW_RELIC_CONFIG_FILENAME to its name. See How the File Is Found.
The file is found but skipped; the log says it could not be loaded. The file throws when required (syntax error, missing module). Fix the error; node -e "require('./newrelic.js')" reproduces it.
No file is read at all. NEW_RELIC_NO_CONFIG_FILE is set. Unset it, or configure everything with environment variables.
An environment variable overrides your file. Environment variables take precedence over the file. Check env | grep NEW_RELIC_.
A value set locally changes after connect. Server-side configuration overrides some settings. Set ignore_server_configuration: true. See Server-Side Configuration.

Settings That Silently Do Something Else

These are behaviors of the configuration code, not bugs in your setup, but they surprise people:

  • Any unrecognized boolean string is true. Only false, f, no, n, disabled, and 0 (case-insensitive) mean false. NEW_RELIC_ENABLED=flase enables the agent. See How values are converted.
  • Invalid enum values fall back to the first allowed value. For example NEW_RELIC_RECORD_SQL=RAW (wrong case) becomes off, not raw.
  • Unknown nested keys are dropped without a warning. A typo such as transaction_tracer: { enable: true } is simply ignored. See Unknown keys.
  • Arrays replace defaults. Setting rules.ignore removes the default socket.io rule; setting attributes.exclude in a new file drops the template's header exclusions.
  • A malformed labels string drops all labels, not only the bad pair.
  • Empty environment variables are skipped, so NEW_RELIC_APP_NAME= does not clear an app_name set in the file.
  • Per-package instrumentation variables keep the package name. instrumentation.@prisma/client.enabled is controlled by NEW_RELIC_INSTRUMENTATION_@PRISMA/CLIENT_ENABLED, which many shells cannot set directly; use the configuration file or env with a quoted name. See instrumentation settings.
  • distributed_tracing.exclude_newrelic_header defaults to true even though its schema description implies false. See Distributed Tracing.
  • validate-config -o with anything other than human (for example -o xml) prints JSON.

No Data in New Relic

Symptom Cause Fix
The log shows connection errors. Network or proxy problems. Check access to the collector host (default collector.newrelic.com, or collector.<region>.nr-data.net derived from the license key). Configure proxy and, for TLS-intercepting proxies, certificates.
Data stops after a deploy with a new license key. Invalid or mistyped key (NR-APM-001 under Agent Control). Check the key; leading and trailing whitespace is trimmed, other characters are not.
The app shows no transactions for your framework. Modules were loaded before the agent. Load the agent first: node -r newrelic app.js. See Loading the Agent.
An ES module app shows no framework transactions. The ESM loader is missing. Start with node --import newrelic/esm-loader.mjs -r newrelic app.js.
A webpack bundle is not instrumented. Instrumented modules were bundled. Use newrelic/load-externals to mark them as externals. See Bundlers.
kafkajs is not instrumented. It is behind a feature flag. Set feature_flag.kafkajs_instrumentation: true.
Nothing is reported from a short-lived script. The process exits before the harvest. Call newrelic.shutdown({ collectPendingData: true }, cb) before exiting.
Lambda logs show nothing from the agent. The agent log is off by default in serverless mode. Set NEW_RELIC_LOG_ENABLED=true and NEW_RELIC_LOG=stdout. See Serverless and Cloud.

Transactions and Naming

Symptom Cause Fix
Many transactions named NormalizedUri/*. The framework router was not recognized, so the backstop applies. Check the framework is supported and loaded after the agent, or name transactions with the API or naming rules. See Transaction Naming.
Too many distinct transaction names. IDs or tokens in names. Use route patterns, naming rules, or url_obfuscation.
A manual transaction never shows up. startBackgroundTransaction/startWebTransaction with a callback that does not return a promise ends only when you call end(). Return a promise from the handler, or call newrelic.getTransaction().end(). See When the transaction ends.
Async work is attributed to the wrong transaction or lost. Context was lost in a custom callback queue or connection pool. Wrap the callback with the shim's bindSegment in custom instrumentation, or start a transaction where the work begins.

API Calls Have No Effect

Symptom Cause
Custom attributes or events are missing. High security mode is on, the api.custom_*_enabled kill switch is off, the key is longer than 255 bytes, or more than 64 custom attributes were added to the transaction. See Attributes, Events, and Metrics.
noticeError errors are missing. The error's status code is in error_collector.ignore_status_codes, error_collector.enabled is false, or api.notice_error_enabled is false.
The debug log shows Not calling <method> because New Relic is disabled. The agent is disabled and the stub API is in use.

Browser Monitoring

getBrowserTimingHeader() returns an HTML comment instead of a script when it cannot build the snippet. The number tells you why:

Comment Meaning
<!-- NREUM: (0) --> Browser monitoring is disabled locally (browser_monitoring.enable: false).
<!-- NREUM: (1) --> No active transaction (and allowTransactionlessInjection not set), or the current transaction is ignored.
<!-- NREUM: (2) --> config.browser_monitoring is missing.
<!-- NREUM: (3) --> The transaction has no name yet.
<!-- NREUM: (4) --> No valid application_id from the server yet.
<!-- NREUM: (5) --> No valid browser_key from the server yet.
<!-- NREUM: (6) --> No js_agent_loader script from the server yet.
<!-- NREUM: (7) --> browser_monitoring.loader is none (usually browser monitoring was turned off on the server).

Codes 4–6 usually mean the agent has not finished connecting; they resolve after the first successful connect. See getBrowserTimingHeader.

The Agent Is Loaded Twice

If two copies of newrelic are required (for example one hoisted and one nested in node_modules), the log shows Attempting to load a second copy of newrelic from ..., using cache instead and the first instance is reused. Remove the duplicate so all code uses the same version.

Performance

  • unresolved_promise_cleanup (feature flag, default true) has a cost in applications creating very many promises. Disabling it can help, but unresolved promises then leak memory.
  • virtual_machine.collect_metrics.enabled adds work on every event loop iteration; disable it if you do not use VM metrics.
  • Lower logging.level back to info after debugging: trace is very verbose.

Getting Help

  • Ask troubleshooting questions in the New Relic Community (linked from the README).
  • File bugs at GitHub issues, with the agent version, Node.js version, and a trace-level log excerpt (remove secrets first).
  • Check NEWS.md for fixes in newer versions.