feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timfish merged 1 commit into from
Jul 23, 2026
Merged

feat: Remove support for initialising via --require#22513

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions MIGRATION.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
"scripts": {
"build": "remix build",
"dev": "remix dev",
"start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
"start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
"typecheck": "tsc",
"clean": "npx rimraf node_modules pnpm-lock.yaml",
"test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
"scripts": {
"build": "remix vite:build && pnpm typecheck",
"dev": "remix vite:dev",
"start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
"start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
"typecheck": "tsc",
"clean": "npx rimraf node_modules pnpm-lock.yaml",
"test:build": "pnpm install && pnpm build",
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
"version": "1.0.0",
"private": true,
"scripts": {
"start": "node --require @sentry/node/preload src/app.js",
"start": "node --import @sentry/node/preload src/app.js",
"clean": "npx rimraf node_modules pnpm-lock.yaml",
"test:build": "pnpm install",
"test:assert": "playwright test"
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/e2e-tests/test-applications/remix-server-timing/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
"scripts": {
"build": "remix vite:build && pnpm typecheck",
"dev": "remix vite:dev",
"start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
"start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
"typecheck": "tsc",
"clean": "npx rimraf node_modules pnpm-lock.yaml",
"test:build": "pnpm install && pnpm build",
Expand Down
3 changes: 0 additions & 3 deletions dev-packages/node-integration-tests/suites/no-code/app.js
View file
Open in desktop

This file was deleted.

9 changes: 0 additions & 9 deletions dev-packages/node-integration-tests/suites/no-code/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
cleanupChildProcesses();
});

test('CJS', async () => {
await createRunner(__dirname, 'app.js')
.withFlags('--require=@sentry/node/init')
.withMockSentryServer()
.expect({ event: EVENT })
.start()
.completed();
});

describe('--import', () => {
test('ESM', async () => {
await createRunner(__dirname, 'app.mjs')
Expand Down
0 ...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs
View file
Open in desktop
File renamed without changes.
6 changes: 3 additions & 3 deletions dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
.completed();
});

test('Should include local variables when instrumenting via --require', async () => {
const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
test('Should include local variables when instrumenting via --import', async () => {
const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

await createRunner(__dirname, 'local-variables-no-sentry.js')
.withFlags(`--require=${requirePath}`)
.withFlags(`--import=${instrumentPath}`)
.expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
.start()
.completed();
Expand Down
5 changes: 1 addition & 4 deletions dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
.withFlags(
extension === 'mjs' ? '--import' : '--require',
path.join(__dirname, `worker-thread/instrument.${extension}`),
)
.withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
.expect({
event: {
level: 'error',
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/node-integration-tests/suites/tracing/mysql/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

// Each case maps to one of the two documented use cases, in opt-in and
// non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
// always loaded via `--import` (esm) / `--require` (cjs) by the runner.
// always loaded via `--import` by the runner.
const CASES = [
// OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
{ label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down
2 changes: 1 addition & 1 deletion dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down
4 changes: 2 additions & 2 deletions ...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down
6 changes: 3 additions & 3 deletions ...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down
4 changes: 2 additions & 2 deletions dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
const eventTraceIds: string[] = [];
const transactionTraceIds: string[] = [];

const runner = createRunner(__dirname, 'server.ts')
.withFlags('--require', join(__dirname, 'instrument.ts'))
const runner = createRunner(__dirname, 'server.js')
.withFlags('--import', join(__dirname, 'instrument.cjs'))
.expect({
event: event => {
eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down
7 changes: 5 additions & 2 deletions dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

const cjsFlags: string[] = ['--require', cjsInstrumentPath];
// `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
// therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
// module loader thread, which the SDK no longer supports.
const cjsFlags: string[] = ['--import', cjsInstrumentPath];
const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
);

esmFlags.unshift('--import', mjsInjectOrchetrionPath);
cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
}

// Copy any additional files/dirs into tmp dir
Expand Down
82 changes: 60 additions & 22 deletions dev-packages/node-integration-tests/utils/runner/createRunner.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
// 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
// so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
// instance, matching how ts-node loaded them.
flags.push('-r', 'tsx/cjs');
flags.push('-r', TS_LOADER);
}

// Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
// flush keeps the event loop alive until queued envelopes reach the
// transport, then the process exits naturally.
//
// We inject the matching loader for the scenario's module system
// (detected by whether `flags` already contains `--import` for the
// instrument file). For ESM scenarios we use `--import auto-flush.mjs`
// so the `import * as Sentry` resolves to the same SDK instance the
// scenario uses; for CJS we use `--require auto-flush.cjs`.
// We inject the loader matching the scenario's module system, so that its
// `Sentry` reference resolves to the same SDK instance the scenario uses —
// see `buildAutoFlushFlags`.
//
// Skipped when no envelopes are expected — these tests (e.g. ANR
// `should-exit`, `ensureNoErrorOutput`) verify the child exits
// naturally and auto-flush would delay that with retrying HTTP
// requests to the fake DSN.
const wantsAutoFlush =
!ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
console.log(...args.map(arg => normalize(arg)));
}

/**
* Extracts the preloaded module paths from Node flags, accepting both the
* two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
* form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
* `suites/no-code/test.ts`).
*/
function getPreloadPaths(flags: readonly string[]): string[] {
const paths: string[] = [];

for (let i = 0; i < flags.length; i++) {
const flag = flags[i] as string;
const [name, ...rest] = flag.split('=');

if (!PRELOAD_FLAGS.includes(name as string)) {
continue;
}

const path = rest.length ? rest.join('=') : flags[++i];
if (path) {
paths.push(path);
}
}

return paths;
}

/**
* Returns Node flags that inject the auto-flush loader matching the scenario's
* module system. ESM scenarios already have `--import` for the instrument
* file — we mirror that with `--import auto-flush.mjs` so both resolve to the
* same `@sentry/node` instance. Otherwise we fall back to `--require
* auto-flush.cjs`.
* module system.
*
* Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
* the file that calls `Sentry.init()` — the last preloaded instrument file if there is
* one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
* the other build's client, which has nothing queued, and no envelope ever arrives.
*
* Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
* or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
* `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
* have to recognise both, otherwise the missed form silently gets
* `auto-flush.cjs` and the flush targets the wrong SDK instance.
* The flag name is no longer a usable signal, since CJS instrument files are preloaded
* with `--import` too (`--require` re-runs the preload on Node's module loader thread).
* The extension is: `.mjs` and extensionless package specifiers such as
* `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
* here because the test package sets no `"type"`.
*
* The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
* through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
* an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
*/
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
if (isEsm) {
return ['--import', join(__dirname, 'auto-flush.mjs')];
}
return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
const initPath =
getPreloadPaths(existingFlags)
.filter(path => path !== TS_LOADER)
.at(-1) ?? testPath;
const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down
2 changes: 1 addition & 1 deletion packages/node/src/init.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
* The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
* The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
* environment variables.
*
* > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down
2 changes: 1 addition & 1 deletion packages/node/src/preload.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
* The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
* The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
* instrumentation, without initializing the Sentry SDK.
*
* This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down
20 changes: 20 additions & 0 deletions packages/node/src/sdk/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
setOpenTelemetryContextAsyncContextStrategy,
setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
options: NodeOptions | undefined = {},
getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
// Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
// spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
// loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
// never runs app code. It is recognizable as the only thread without a `parentPort`:
// user-created workers always have one and are legitimately instrumented.
if (!isMainThread && !parentPort) {
return undefined;
}

if (getEntryPointType() === 'require') {
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.warn(
'[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
);
});
}

applySdkMetadata(options, 'node');

// Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down
2 changes: 1 addition & 1 deletion packages/node/src/utils/entry-point.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

const joinedArgs = execArgv.join(' ');
const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));

@cursorcursorBotJul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads

Medium Severity

The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.

Additional Locations (1)
Fix in CursorFix in Web

Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.

@timfishtimfishJul 22, 2026

Copy link
Copy Markdown
CollaboratorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok


return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat: Remove support for initialising via --require#22513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

timfish
merged 1 commit into

from

Jul 23, 2026
 Merged


feat: Remove support for initialising via --require#22513
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


18 changes: 18 additions & 0 deletions
MIGRATION.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.

The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.

### Initializing via `--require` is no longer supported

Affected SDKs: `@sentry/node` and all dependents.

Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.

Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:

```bash
# Before
node --require ./instrument.js app.js

# After
node --import ./instrument.js app.js
```

The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.

### Span streaming is now the default

Affected SDKs: All SDKs.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix build",
 "dev": "remix dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && npx playwright install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';

// The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
// don't prove they came from the BUILD-time transform: if the Vite plugin silently
// failed to load, the deps would stay external and the runtime `--require` hook would
// failed to load, the deps would stay external and the runtime `--import` hook would
// inject the channels at runtime instead - the span tests would still pass. These
// assertions inspect the built server bundle directly so a broken plugin can't hide
// behind that runtime fallback. Only relevant in the orchestrion variant.
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@
 "version": "1.0.0",
 "private": true,
 "scripts": {
 "start": "node --require @sentry/node/preload src/app.js",
 "start": "node --import @sentry/node/preload src/app.js",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install",
 "test:assert": "playwright test"
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@
 "scripts": {
 "build": "remix vite:build && pnpm typecheck",
 "dev": "remix vite:dev",
 "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
 "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
 "typecheck": "tsc",
 "clean": "npx rimraf node_modules pnpm-lock.yaml",
 "test:build": "pnpm install && pnpm build",
Expand Down

3 changes: 0 additions & 3 deletions
dev-packages/node-integration-tests/suites/no-code/app.js

View file


Open in desktop


This file was deleted.


9 changes: 0 additions & 9 deletions
dev-packages/node-integration-tests/suites/no-code/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -17,15 +17,6 @@ describe('no-code init', () => {
 cleanupChildProcesses();
 });

 test('CJS', async () => {
 await createRunner(__dirname, 'app.js')
 .withFlags('--require=@sentry/node/init')
 .withMockSentryServer()
 .expect({ event: EVENT })
 .start()
 .completed();
 });

 describe('--import', () => {
 test('ESM', async () => {
 await createRunner(__dirname, 'app.mjs')
Expand Down

0
...alVariables/local-variables-instrument.js → ...lVariables/local-variables-instrument.cjs

View file


Open in desktop


File renamed without changes.


6 changes: 3 additions & 3 deletions
dev-packages/node-integration-tests/suites/public-api/LocalVariables/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
 .completed();
 });

 test('Should include local variables when instrumenting via --require', async () => {
 const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
 test('Should include local variables when instrumenting via --import', async () => {
 const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');

 await createRunner(__dirname, 'local-variables-no-sentry.js')
 .withFlags(`--require=${requirePath}`)
 .withFlags(`--import=${instrumentPath}`)
 .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
 .start()
 .completed();
Expand Down

5 changes: 1 addition & 4 deletions
dev-packages/node-integration-tests/suites/public-api/OnUncaughtException/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -136,10 +136,7 @@ describe('OnUncaughtException integration', () => {
 conditionalTest({ min: 20 })('Worker thread error handling Node 20+', () => {
 test.each(['mjs', 'js'])('should not interfere with worker thread error handling ".%s"', async extension => {
 const runner = createRunner(__dirname, `worker-thread/caught-worker.${extension}`)
 .withFlags(
 extension === 'mjs' ? '--import' : '--require',
 path.join(__dirname, `worker-thread/instrument.${extension}`),
 )
 .withFlags('--import', path.join(__dirname, `worker-thread/instrument.${extension}`))
 .expect({
 event: {
 level: 'error',
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/mysql/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -66,7 +66,7 @@ describe('mysql auto instrumentation', () => {

 // Each case maps to one of the two documented use cases, in opt-in and
 // non-opt-in form. `flags` are extra Node CLI flags; the instrument file is
 // always loaded via `--import` (esm) / `--require` (cjs) by the runner.
 // always loaded via `--import` by the runner.
 const CASES = [
 // OpenTelemetry default — no opt-in, no injection. (OTel does not support ESM.)
 { label: 'opentelemetry (default)', env: {}, flags: [], origin: undefined, failsOnEsm: true },
Expand Down

2 changes: 1 addition & 1 deletion
dev-packages/node-integration-tests/suites/tracing/postgres/instrument-orchestrion.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
// Opting in via `experimentalUseDiagnosticsChannelInjection()` before `init()`
// is all that's needed. Because this file is loaded
// (via `--import`/`--require`) before the scenario imports `pg`,
// (via `--import`) before the scenario imports `pg`,
// `Sentry.init()` synchronously installs the channel-injection hooks, so the
// OTel `Postgres` instrumentation is swapped for the diagnostics-channel one.
import * as Sentry from '@sentry/node';
Expand Down

4 changes: 2 additions & 2 deletions
...raceid-recycling-with-spans/instrument.ts → ...aceid-recycling-with-spans/instrument.cjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
import * as Sentry from '@sentry/node';
import { loggingTransport } from '@sentry-internal/node-integration-tests';
const Sentry = require('@sentry/node');
const { loggingTransport } = require('@sentry-internal/node-integration-tests');

Sentry.init({
 dsn: 'https://public@dsn.ingest.sentry.io/1337',
Expand Down

6 changes: 3 additions & 3 deletions
...ng/traceid-recycling-with-spans/server.ts → ...ng/traceid-recycling-with-spans/server.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import * as Sentry from '@sentry/node';
import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
import express from 'express';
const Sentry = require('@sentry/node');
const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
const express = require('express');

const app = express();

Expand Down

4 changes: 2 additions & 2 deletions
dev-packages/node-integration-tests/suites/tracing/traceid-recycling-with-spans/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,8 +10,8 @@ test('errors and transactions get a unique traceId per request, when tracing is
 const eventTraceIds: string[] = [];
 const transactionTraceIds: string[] = [];

 const runner = createRunner(__dirname, 'server.ts')
 .withFlags('--require', join(__dirname, 'instrument.ts'))
 const runner = createRunner(__dirname, 'server.js')
 .withFlags('--import', join(__dirname, 'instrument.cjs'))
 .expect({
 event: event => {
 eventTraceIds.push(event.contexts?.trace?.trace_id || '');
Expand Down

7 changes: 5 additions & 2 deletions
dev-packages/node-integration-tests/utils/runner/createEsmAndCjsTests.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -241,7 +241,10 @@ function prepareTmpDir(
 const cjsScenarioPath = join(tmpDirPath, esmScenarioBasename.replace('.mjs', '.cjs'));
 const cjsInstrumentPath = join(tmpDirPath, esmInstrumentBasename.replace('.mjs', '.cjs'));

 const cjsFlags: string[] = ['--require', cjsInstrumentPath];
 // `--import` for both: the `.cjs` extension is what makes Node load the instrument file (and
 // therefore the SDK) as CommonJS. `--require` would additionally re-run the preload on Node's
 // module loader thread, which the SDK no longer supports.
 const cjsFlags: string[] = ['--import', cjsInstrumentPath];
 const esmFlags: string[] = ['--import', esmInstrumentPathForRun];

 async function createTmpDir(): Promise<void> {
Expand DownExpand Up@@ -274,7 +277,7 @@ experimentalUseDiagnosticsChannelInjection();`,
 );

 esmFlags.unshift('--import', mjsInjectOrchetrionPath);
 cjsFlags.unshift('--require', cjsInjectOrchetrionPath);
 cjsFlags.unshift('--import', cjsInjectOrchetrionPath);
 }

 // Copy any additional files/dirs into tmp dir
Expand Down

82 changes: 60 additions & 22 deletions
dev-packages/node-integration-tests/utils/runner/createRunner.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,12 @@ const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
const COMPILE_CACHE_ENV: Record<string, string> =
 NODE_MAJOR >= 22 ? { NODE_COMPILE_CACHE: join(tmpdir(), 'sentry-node-it-compile-cache') } : {};

/** Node flags that preload a module before the entry point. */
const PRELOAD_FLAGS = ['--import', '--require', '-r'];

/** tsx's CommonJS require hook, preloaded for `.ts` scenarios. */
const TS_LOADER = 'tsx/cjs';

export const CLEANUP_STEPS = new Set<VoidFunction>();

export function cleanupChildProcesses(): void {
Expand DownExpand Up@@ -147,7 +153,7 @@ export function createRunner(...paths: string[]) {
 // 22+ gives the scenario a different `@sentry/node` instance than the CJS instrument/auto-flush,
 // so instrumentation and flushing target the wrong SDK object. The require hook keeps one CJS
 // instance, matching how ts-node loaded them.
 flags.push('-r', 'tsx/cjs');
 flags.push('-r', TS_LOADER);
 }

 // Cleanup steps registered by this specific runner (child process, docker, mock server). They are
Expand DownExpand Up@@ -417,19 +423,17 @@ export function createRunner(...paths: string[]) {
 // flush keeps the event loop alive until queued envelopes reach the
 // transport, then the process exits naturally.
 //
 // We inject the matching loader for the scenario's module system
 // (detected by whether `flags` already contains `--import` for the
 // instrument file). For ESM scenarios we use `--import auto-flush.mjs`
 // so the `import * as Sentry` resolves to the same SDK instance the
 // scenario uses; for CJS we use `--require auto-flush.cjs`.
 // We inject the loader matching the scenario's module system, so that its
 // `Sentry` reference resolves to the same SDK instance the scenario uses —
 // see `buildAutoFlushFlags`.
 //
 // Skipped when no envelopes are expected — these tests (e.g. ANR
 // `should-exit`, `ensureNoErrorOutput`) verify the child exits
 // naturally and auto-flush would delay that with retrying HTTP
 // requests to the fake DSN.
 const wantsAutoFlush =
 !ensureNoErrorOutput && (expectedEnvelopes.length > 0 || (expectedEnvelopeHeaders?.length ?? 0) > 0);
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags), ...flags] : flags;
 const childFlags = wantsAutoFlush ? [...buildAutoFlushFlags(flags, testPath), ...flags] : flags;

 child = spawn('node', [...childFlags, testPath], { env });

Expand DownExpand Up@@ -651,25 +655,59 @@ function log(...args: unknown[]): void {
 console.log(...args.map(arg => normalize(arg)));
}

/**
 * Extracts the preloaded module paths from Node flags, accepting both the
 * two-element form (`--import foo`, e.g. `withInstrument`) and the single-element
 * form (`--import=foo`, e.g. `withFlags('--import=@sentry/node/init')` in
 * `suites/no-code/test.ts`).
 */
function getPreloadPaths(flags: readonly string[]): string[] {
 const paths: string[] = [];

 for (let i = 0; i < flags.length; i++) {
 const flag = flags[i] as string;
 const [name, ...rest] = flag.split('=');

 if (!PRELOAD_FLAGS.includes(name as string)) {
 continue;
 }

 const path = rest.length ? rest.join('=') : flags[++i];
 if (path) {
 paths.push(path);
 }
 }

 return paths;
}

/**
 * Returns Node flags that inject the auto-flush loader matching the scenario's
 * module system. ESM scenarios already have `--import` for the instrument
 * file — we mirror that with `--import auto-flush.mjs` so both resolve to the
 * same `@sentry/node` instance. Otherwise we fall back to `--require
 * auto-flush.cjs`.
 * module system.
 *
 * Which of the two SDK builds (CJS or ESM) holds the queued envelopes is decided by
 * the file that calls `Sentry.init()` — the last preloaded instrument file if there is
 * one, otherwise the scenario itself. Getting this wrong is silent: the flush targets
 * the other build's client, which has nothing queued, and no envelope ever arrives.
 *
 * Node accepts both `--import foo` (two array elements, e.g. `withInstrument`
 * or `withFlags('--import', foo)`) and `--import=foo` (one element, e.g.
 * `withFlags('--import=@sentry/node/init')` in `suites/no-code/test.ts`); we
 * have to recognise both, otherwise the missed form silently gets
 * `auto-flush.cjs` and the flush targets the wrong SDK instance.
 * The flag name is no longer a usable signal, since CJS instrument files are preloaded
 * with `--import` too (`--require` re-runs the preload on Node's module loader thread).
 * The extension is: `.mjs` and extensionless package specifiers such as
 * `@sentry/node/init` resolve as ESM, while `.cjs`, `.js` and `.ts` are all CommonJS
 * here because the test package sets no `"type"`.
 *
 * The CJS loader stays on `--require`: any `--import` makes Node resolve the entry point
 * through the ESM loader, which rejects the `.ts` scenarios that `tsx/cjs` handles. Unlike
 * an instrument file it never calls `Sentry.init()`, so the loader thread is not a concern.
 */
function buildAutoFlushFlags(existingFlags: readonly string[]): string[] {
 const isEsm = existingFlags.some(flag => flag === '--import' || flag.startsWith('--import='));
 if (isEsm) {
 return ['--import', join(__dirname, 'auto-flush.mjs')];
 }
 return ['--require', join(__dirname, 'auto-flush.cjs')];
function buildAutoFlushFlags(existingFlags: readonly string[], testPath: string): string[] {
 const initPath =
 getPreloadPaths(existingFlags)
 .filter(path => path !== TS_LOADER)
 .at(-1) ?? testPath;
 const isEsm = initPath.endsWith('.mjs') || !/\.[cm]?[jt]s$/.test(initPath);

 return isEsm ? ['--import', join(__dirname, 'auto-flush.mjs')] : ['--require', join(__dirname, 'auto-flush.cjs')];
}

function expectErrorEvent(item: Event, expected: ExpectedEvent): void {
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/init.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
import { init } from './sdk';

/**
 * The @sentry/node/init export can be used with the node --import and --require args to initialize the SDK entirely via
 * The @sentry/node/init export can be used with the node --import arg to initialize the SDK entirely via
 * environment variables.
 *
 * > SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 SENTRY_TRACES_SAMPLE_RATE=1.0 node --import=@sentry/node/init app.mjs
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/preload.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,7 @@ const integrationsStr = process.env.SENTRY_PRELOAD_INTEGRATIONS;
const integrations = integrationsStr ? integrationsStr.split(',').map(integration => integration.trim()) : undefined;

/**
 * The @sentry/node/preload export can be used with the node --import and --require args to preload the OTEL
 * The @sentry/node/preload export can be used with the node --import arg to preload the OTEL
 * instrumentation, without initializing the Sentry SDK.
 *
 * This is useful if you cannot initialize the SDK immediately, but still want to preload the instrumentation,
Expand Down

20 changes: 20 additions & 0 deletions
packages/node/src/sdk/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,6 +21,7 @@ import {
 setOpenTelemetryContextAsyncContextStrategy,
 setupEventContextTrace,
} from '@sentry/opentelemetry';
import { isMainThread, parentPort } from 'node:worker_threads';
import { DEBUG_BUILD } from '../debug-build';
import { childProcessIntegration } from '../integrations/childProcess';
import { consoleIntegration } from '../integrations/console';
Expand All@@ -38,6 +39,7 @@ import { systemErrorIntegration } from '../integrations/systemError';
import { getAutoPerformanceIntegrations } from '../integrations/tracing';
import { makeNodeTransport } from '../transports';
import type { NodeClientOptions, NodeOptions } from '../types';
import { getEntryPointType } from '../utils/entry-point';
import { getSpotlightConfig } from '../utils/spotlight';
import { defaultStackParser, getSentryRelease } from './api';
import { NodeClient } from './client';
Expand DownExpand Up@@ -150,6 +152,24 @@ function _init(
 options: NodeOptions | undefined = {},
 getDefaultIntegrationsImpl: (options: Options) => Integration[],
): NodeClient | undefined {
 // Node re-runs `--require` preloads (though not `--import` ones) on the module loader thread it
 // spawns for `Module.register()`, which `init()` itself triggers (channel injection, the ESM
 // loader hook). So a `--require`d instrument file re-enters `init()` there, on a thread that
 // never runs app code. It is recognizable as the only thread without a `parentPort`:
 // user-created workers always have one and are legitimately instrumented.
 if (!isMainThread && !parentPort) {
 return undefined;
 }

 if (getEntryPointType() === 'require') {
 consoleSandbox(() => {
 // eslint-disable-next-line no-console
 console.warn(
 '[Sentry] Initializing the SDK via the Node `--require` flag is no longer supported, because Node re-runs `--require` preloads on its module loader thread. Use `--import` instead: `node --import ./instrument.js app.js`',
 );
 });
 }

 applySdkMetadata(options, 'node');

 // Resolve the tracing-affecting options (e.g. `SENTRY_TRACES_SAMPLE_RATE`) up front so that both
Expand Down

2 changes: 1 addition & 1 deletion
packages/node/src/utils/entry-point.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@ export function parseProcessPaths(proc: ProcessInterface): ProcessArgs {

 const joinedArgs = execArgv.join(' ');
 const importPaths = Array.from(joinedArgs.matchAll(/--import[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/--require[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
 const requirePaths = Array.from(joinedArgs.matchAll(/(?:--require|-r)[ =](\S+)/g)).map(e => resolve(cwd, e[1] || ''));
@cursorcursorBotJul 22, 2026

Copy link


Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Require warning misses package preloads
Medium Severity
The new --require migration warning relies on getEntryPointType(), but parseProcessPaths resolves preload targets with path.resolve(cwd, ...). Package specifiers like @sentry/node/init never match real stack filenames under node_modules, so the documented no-code --require entry points silently skip the warning.
Additional Locations (1)
Fix in CursorFix in Web
Reviewed by Cursor Bugbot for commit 143a4cc. Configure here.
@timfishtimfishJul 22, 2026

Copy link


Copy Markdown

CollaboratorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's ok

 return { appPath, importPaths, requirePaths };
}
Expand Down
Loading
Loading