Most init() calls follow "last call wins, with no warning" today. About seven entry points add their own guard, and those guards do not agree.
Proposed rule:
One active client per init() target. The first init() wins. A later init() changes nothing, returns the active client, and warns. To reconfigure, call close() first.
To make this true:
- Put the guard in one shared place:
initAndBind, plus the client creation in Node's _init and Vercel Edge's init. Do not put it in each framework wrapper. The wrappers can then drop their own guards.
- Base the guard on "there is a bound client that is not closed". Make
close() unbind the client (or mark it closed) so that close(); init() works.
- Always return the existing client, never
undefined.
- Warn through
consoleSandbox even when debug is off, because a repeated call is a real misconfiguration. Nuxt already does this. The exception is a repeated call that the SDK expects, such as a server bundle and an --import preload that both run the config (Nuxt, Hono node). For those, log only in debug mode.
- Keep Cloudflare's
cacheClient: false as the documented way to get a new client on each call. It fits the rule: "first wins" becomes "first wins per isolate". Its debug warning on a DSN change is correct, and it could compare more options than the DSN.
The rule is short to explain, and the result is predictable: a user never gets half of one config and half of another. It also matches what the more mature server wrappers (Next.js server, Remix server, Nuxt server, Cloudflare, Hono node) already chose on their own.
Related: #24520
Spec/analysis:
sentry-init-return-value-report.md
Most
init()calls follow "last call wins, with no warning" today. About seven entry points add their own guard, and those guards do not agree.Proposed rule:
To make this true:
initAndBind, plus the client creation in Node's_initand Vercel Edge'sinit. Do not put it in each framework wrapper. The wrappers can then drop their own guards.close()unbind the client (or mark it closed) so thatclose(); init()works.undefined.consoleSandboxeven whendebugis off, because a repeated call is a real misconfiguration. Nuxt already does this. The exception is a repeated call that the SDK expects, such as a server bundle and an--importpreload that both run the config (Nuxt, Hono node). For those, log only in debug mode.cacheClient: falseas the documented way to get a new client on each call. It fits the rule: "first wins" becomes "first wins per isolate". Its debug warning on a DSN change is correct, and it could compare more options than the DSN.The rule is short to explain, and the result is predictable: a user never gets half of one config and half of another. It also matches what the more mature server wrappers (Next.js server, Remix server, Nuxt server, Cloudflare, Hono node) already chose on their own.
Related: #24520
Spec/analysis:
sentry-init-return-value-report.md