Commit 6805115

- `Sentry.init()` follows one rule for repeated calls: the first call wins. See

`docs/repeated-init.md` before you add or change an `init()`.

- **feat(core)**: `Sentry.init()` now warns when it runs while a client is still active. For now, the new client still replaces the active client, but the active client is not closed, so state from both can mix. Call `Sentry.init()` once, or call `await Sentry.close()` before you call it again. `Sentry.close()` now unbinds the client it closes, so after `close()`, `getClient()` returns `undefined`, `isInitialized()` returns `false`, and a later `init()` sets up a new client. In `@sentry/cloudflare`, later requests no longer reuse the isolate's cached client once it is closed or closing. On the server, `@sentry/nextjs` and `@sentry/remix` now return the active client from a repeated `init()` call, not `undefined`.

import * as Sentry from '@sentry/node';

import { loggingTransport } from '@sentry-internal/node-integration-tests';

async function run(): Promise<void> {

Sentry.init({

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '1.0',

transport: loggingTransport,

});

// The root scope still holds the closed client after this.

await Sentry.withIsolationScope(() => Sentry.close());

Sentry.init({

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '2.0',

transport: loggingTransport,

});

Sentry.captureMessage('after close in a child scope and init');

import * as Sentry from '@sentry/node';

import { loggingTransport } from '@sentry-internal/node-integration-tests';

async function run(): Promise<void> {

Sentry.init({

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '1.0',

transport: loggingTransport,

});

await Sentry.close();

Sentry.init({

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '2.0',

transport: loggingTransport,

});

Sentry.captureMessage('after close and init');

import * as Sentry from '@sentry/node';

import { loggingTransport } from '@sentry-internal/node-integration-tests';

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '1.0',

transport: loggingTransport,

dsn: 'https://public@dsn.ingest.sentry.io/1337',

release: '2.0',

transport: loggingTransport,

import { afterAll, expect, test } from 'vitest';

import { cleanupChildProcesses, createRunner } from '../../../utils/runner';

afterAll(() => {

cleanupChildProcesses();

const REPEATED_INIT_WARNING = '`Sentry.init()` was called more than once';

test('warns on a repeated init and sends events with the new client', async () => {

const runner = createRunner(__dirname, 'scenario-repeated.ts')

.expect({ event: { message: 'after repeated init', release: '2.0' } })

.start();

await runner.completed();

expect(runner.getLogs().join('\n')).toContain(REPEATED_INIT_WARNING);

test('does not warn on init after close and sends events with the new client', async () => {

const runner = createRunner(__dirname, 'scenario-close.ts')

.expect({ event: { message: 'after close and init', release: '2.0' } })

.start();

await runner.completed();

expect(runner.getLogs().join('\n')).not.toContain(REPEATED_INIT_WARNING);

test('does not warn on init after close in a child scope', async () => {

const runner = createRunner(__dirname, 'scenario-close-in-scope.ts')

.expect({ event: { message: 'after close in a child scope and init', release: '2.0' } })

.start();

await runner.completed();

expect(runner.getLogs().join('\n')).not.toContain(REPEATED_INIT_WARNING);

This document records how `Sentry.init()` should act when an app calls it

more than once. Use it when you add or change an `init()` in any SDK.

"Active" means a client is bound to the current scope and is not closed.

`Sentry.close()` closes the client and unbinds it, so a later `init()` sets

up a new client. Other scopes can still hold the closed client (for example,

when `close()` runs inside a request, or when code calls `client.close()`

directly), so a check for "already initialized" must not use `getClient()`

alone.

A repeated `init()` is not supported. Until the next major version, most

SDKs still replace the client (see below). Do not depend on that.

When `init()` replaces a client, nothing closes the old one:

- Buffered logs, metrics, spans, client reports, and flush timers stay on

the old client.

- `setupOnce` runs only for the first client, because the list of

installed integrations is global. The result mixes settings from both

calls.

- `initialScope` merges into the current scope on each call.

"First wins" never gives a user half of one config and half of another.

| Entry point | Repeated call |

| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| `initAndBind` (browser and its wrappers, Deno), Node `_init`, Vercel Edge | Warns, then replaces the client. Returns the new client. |

| Next.js server, Remix server, Hono Node | Keeps the first client and returns it. Logs in debug mode only. |

| Hono Bun and Deno | Keeps the first client and returns it. Warns with its own text. |

| Nuxt server | Keeps the first client and returns it. Logs that a `--import` preload is no longer needed. |

| Cloudflare (default) | Keeps the first client of the isolate and returns it, unless that client is closed or closing. `cacheClient: false` makes a new client on each call, with no warning. |

| Next.js edge | Warns, then replaces the client. Returns `void`. |

The shared warning lives in `warnIfClientIsActive()` in

`packages/core/src/sdk.ts`. Core exports it as

`_INTERNAL_warnIfClientIsActive` for SDKs that build their client without

`initAndBind`.

A wrapper that expects a repeated call, such as a server bundle and a

`--import` preload that both run the config, keeps its own guard and

returns early. The shared warning then does not show. Guards use

`getActiveClient()` (exported as `_INTERNAL_getActiveClient`), which

returns the bound client only if it is not closed.

1. Move the "first wins" guard into `initAndBind`, Node's `_init`, and

Vercel Edge's `init`. Remove the guards in each wrapper.

2. Switch browser to "first wins". For two apps on one page, point users

to separate clients that are not bound with `init()` (see #24883).

3. Make Next.js edge return the client.

A test that calls `init()` again without a reset now prints the warning.

Reset between tests with one of these:

- `getCurrentScope().setClient(undefined)`, or a helper that clears the

carrier (`getMainCarrier().__SENTRY__ = undefined`).

- `await Sentry.close()`. This also flushes, so it is slower.

The warning goes through `consoleSandbox`, which calls the method stored

in `originalConsoleMethods`. To assert on it, replace

`originalConsoleMethods.warn` with a mock. A spy on `console.warn` misses

it once the console integration is set up.

import { afterEach, vi } from 'vitest';

afterEach(() => {

SentryBrowser.getCurrentScope().setClient(undefined);

});

import { getCurrentScope, getMainCarrier, SentrySpan, spanToJSON, startSpan } from '@sentry/core';

import { beforeEach, describe, it } from 'vitest';

beforeEach(() => {

getCurrentScope().setClient(undefined);

});