Sentry Node.js: preload instrument.js before everything else

TL;DR

Create instrument.js (or.mjs for ESM) at the project root: `js const Sentry = require("@sentry/node"); Sentry.init({ dsn: "\_\_\_PUBLIC\_DSN\_\_\_", tracesSampleRate: 0.1, // docs show 1.0; lower it for production }); Then preload it so it runs before your app code: node --import./instrument.js app.js For ESM use instrument.mjs and node --import./instrument.mjs app.mjs.

When to use

You are seeing this: The whole point is ordering: anything imported before Sentry.init()` runs misses auto-instrumentation (http, db, etc.). Use this skill when you run into "Sentry Node.js: preload instrument.js before everything else".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

The pattern

Create instrument.js (or .mjs for ESM) at the project root:

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  tracesSampleRate: 0.1, // docs show 1.0; lower it for production
});

Then preload it so it runs before your app code:

node --import ./instrument.js app.js

For ESM use instrument.mjs and node --import ./instrument.mjs app.mjs. The whole point is ordering: anything imported before Sentry.init() runs misses auto-instrumentation (http, db, etc.). If you use a bundler like Vite, follow the bundler setup docs instead of the preload flag.

Version floor

Current docs require Node >=20.19.0 ([22), ]=22.12.0 ([23), or ]=23.2.0. Older Node versions silently lose instrumentation or fail to load. If your Dockerfile pins node:18 or node:20-slim from last year, this is the first thing to check when events stop.

v11 changes that bite

• Span streaming is the default: spans ship in batches as they finish instead of one transaction at the end. beforeSendTransaction and ignoreTransactions no longer do anything.
• sendDefaultPii is gone, replaced by dataCollection with per-category control, and the v11 default collects MORE than the v10 default did. If you relied on v10's restrictive default, set the categories explicitly.
• setTag/setExtra no longer land on spans; use setAttribute/setAttributes for anything that must be searchable on spans.

Verify

Drop a caught exception behind a setTimeout (like the docs verify snippet), run with the preload flag, and confirm the issue appears. If not, check the DSN and that no adblocker or egress proxy sits between the host and the ingest endpoint.

Researched against live Sentry docs 2026-09-26. The Node.js setup page (docs.sentry.io/platforms/javascript/guides/node/) requires an instrument.(js|mjs) file loaded via node --import before the app starts, with the comment Ensure to call this before importing any other modules, and lists the supported Node range (>=20.19.0 [22.0.0 || ]=22.12.0 [23.0.0 || ]=23.2.0). The v10-to-v11 migration guide (docs.sentry.io/platforms/javascript/migration/v10-to-v11/) documents span streaming as the new default, sendDefaultPii replaced by dataCollection, and Node 20.19.0 as the new minimum.