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
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. Onlyfalse,f,no,n,disabled, and0(case-insensitive) mean false.NEW_RELIC_ENABLED=flaseenables 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) becomesoff, notraw. - 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.ignoreremoves the default socket.io rule; settingattributes.excludein a new file drops the template's header exclusions. - A malformed
labelsstring drops all labels, not only the bad pair. - Empty environment variables are skipped, so
NEW_RELIC_APP_NAME=does not clear anapp_nameset in the file. - Per-package instrumentation variables keep the package name.
instrumentation.@prisma/client.enabledis controlled byNEW_RELIC_INSTRUMENTATION_@PRISMA/CLIENT_ENABLED, which many shells cannot set directly; use the configuration file orenvwith a quoted name. Seeinstrumentationsettings. distributed_tracing.exclude_newrelic_headerdefaults totrueeven though its schema description impliesfalse. See Distributed Tracing.validate-config -owith anything other thanhuman(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, defaulttrue) has a cost in applications creating very many promises. Disabling it can help, but unresolved promises then leak memory.virtual_machine.collect_metrics.enabledadds work on every event loop iteration; disable it if you do not use VM metrics.- Lower
logging.levelback toinfoafter debugging:traceis 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.