From b50bdf875bc478e642484f291a638748fe4e5ea0 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:56:24 +0000 Subject: [PATCH] fix(cli): Warn that hard-coded SDKs miss the free-port fallback When the Local daemon holds port 8969, a plain `local run` captures on a free port. The daemon drops traffic that isn't for a session, so an SDK that hard-codes 8969 lost everything with no hint. The notice now names the port in use and says to read SENTRY_SPOTLIGHT, the same way the --verify fallback does. Both notices come from one helper so their wording can't drift. Co-Authored-By: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com> --- apps/cli-docs/src/fragments/commands/local.md | 2 +- packages/cli/src/commands/local/run.ts | 38 +++++++++++++------ packages/cli/test/commands/local/run.test.ts | 11 ++++-- 3 files changed, 35 insertions(+), 16 deletions(-) diff --git a/apps/cli-docs/src/fragments/commands/local.md b/apps/cli-docs/src/fragments/commands/local.md index 9db9ec7ab..44fde7191 100644 --- a/apps/cli-docs/src/fragments/commands/local.md +++ b/apps/cli-docs/src/fragments/commands/local.md @@ -12,7 +12,7 @@ Runs a command with `SENTRY_SPOTLIGHT` set to the local server's URL. Node.js an If nothing is listening on the port, a server is started in the background and shut down when your command exits. If something already is — the Spotlight desktop app's own sidecar, or a `sentry local serve` in another terminal — the command attaches to it as an SSE consumer, so events still tail to your terminal either way. -The Local daemon behind `--session` is the exception: it only takes session traffic. When it holds port 8969, a plain `local run` captures on a free port and says so. Add `--session ` to capture into the daemon instead. With an explicit `--port` that the daemon holds, the command stops with an error. +The Local daemon behind `--session` is the exception: it only takes session traffic. When it holds port 8969, a plain `local run` captures on a free port and says so. An SDK that hard-codes 8969 won't reach that port, so make sure it reads `SENTRY_SPOTLIGHT`. Add `--session ` to capture into the daemon instead. With an explicit `--port` that the daemon holds, the command stops with an error. With no command, `local run` picks one from the project, in this order: diff --git a/packages/cli/src/commands/local/run.ts b/packages/cli/src/commands/local/run.ts index 18e18c9a9..ccc91ff9b 100644 --- a/packages/cli/src/commands/local/run.ts +++ b/packages/cli/src/commands/local/run.ts @@ -284,6 +284,22 @@ async function startBackgroundServer({ }; } +/** + * Say that this run listens on `boundPort` because `defaultPort` is taken. + * An SDK that hard-codes the default port sends there instead, and the + * daemon drops traffic that isn't for a session without a word, so the + * notice says to use SENTRY_SPOTLIGHT. + * + * @param reason - Why the default port is taken, e.g. "is in use" + */ +function freePortNotice( + defaultPort: number, + boundPort: number, + reason: string, +): string { + return `Port ${defaultPort} ${reason}, so this run listens on port ${boundPort} instead. SDKs that hard-code ${defaultPort} won't reach it; make sure they read SENTRY_SPOTLIGHT.`; +} + /** * Get a live event tail on `host:port`, whichever way is available. * @@ -303,7 +319,7 @@ async function openEventTail({ const url = formatLocalServerUrl(host, port); let running = false; - let listenPort = port; + let heldByDaemon = false; try { running = await isServerRunning(url); } catch (err) { @@ -318,10 +334,7 @@ async function openEventTail({ } // The daemon's receiver only takes session traffic, and it stays up while // it retains sessions, so a plain run gets its own receiver instead. - logger.info( - `The Local daemon is using port ${port}, so this run captures on a free port. Add --session to capture into the daemon instead.`, - ); - listenPort = 0; + heldByDaemon = true; } if (running) { @@ -335,18 +348,23 @@ async function openEventTail({ }); } - if (listenPort === port) { + if (!heldByDaemon) { logger.info("No server detected, starting one in the background..."); } try { const bg = await startBackgroundServer({ maxEnvelopes, - port: listenPort, + port: heldByDaemon ? 0 : port, host, activeFilters, useJson, showAttributes, }); + if (heldByDaemon) { + logger.info( + `${freePortNotice(port, Number(new URL(bg.url).port), "is held by the Local daemon")} Add --session to capture into the daemon instead.`, + ); + } logger.info(`Background server listening on ${bold(bg.url)}`); return bg; } catch (err) { @@ -900,8 +918,8 @@ async function listenForVerify( PORT_IN_USE_FIELD, ); } - logger.info(`Port ${DEFAULT_PORT} is in use; verifying on a free port`); const bound = await tryListen(app, 0, host, { retries: 0 }); + logger.info(freePortNotice(DEFAULT_PORT, bound.port, "is in use")); return { ...bound, fellBack: true }; } } @@ -1067,9 +1085,7 @@ async function* runWithVerify( if (fellBack) { // An SDK that ignores SENTRY_SPOTLIGHT still sends to the busy default // port, so it reaches whatever holds that port instead of this receiver. - logger.warn( - `Verify used port ${boundPort} because ${DEFAULT_PORT} was busy. Make sure your SDK reads SENTRY_SPOTLIGHT instead of a hard-coded port.`, - ); + logger.warn(freePortNotice(DEFAULT_PORT, boundPort, "is in use")); } throw new VerifyFailedError( `Verification timed out after ${verifyTimeout}s — no events received from the SDK`, diff --git a/packages/cli/test/commands/local/run.test.ts b/packages/cli/test/commands/local/run.test.ts index 47b2b32be..9613bb587 100644 --- a/packages/cli/test/commands/local/run.test.ts +++ b/packages/cli/test/commands/local/run.test.ts @@ -1109,6 +1109,7 @@ describe("sentry local run --verify receiver", () => { test("says which port it used when verify on a fallback port times out", async () => { const busy = makeDefaultPortBusy(); + const info = vi.spyOn(logger, "info").mockImplementation(() => {}); const warn = vi.spyOn(logger, "warn").mockImplementation(() => {}); const context = makeParsedRunContext(); try { @@ -1131,10 +1132,12 @@ describe("sentry local run --verify receiver", () => { ); expect(context.process.exitCode).toBe(EXIT.VERIFY_FAILED); const port = new URL(spawnCapture.env?.SENTRY_SPOTLIGHT ?? "").port; - expect(warn).toHaveBeenCalledWith( - `Verify used port ${port} because ${DEFAULT_PORT} was busy. Make sure your SDK reads SENTRY_SPOTLIGHT instead of a hard-coded port.`, - ); + const notice = `Port ${DEFAULT_PORT} is in use, so this run listens on port ${port} instead. SDKs that hard-code ${DEFAULT_PORT} won't reach it; make sure they read SENTRY_SPOTLIGHT.`; + // Once when it binds, and again when nothing arrived. + expect(info).toHaveBeenCalledWith(notice); + expect(warn).toHaveBeenCalledWith(notice); } finally { + info.mockRestore(); warn.mockRestore(); busy.mockRestore(); } @@ -1217,7 +1220,7 @@ describe("sentry local run messages", () => { expect(Number(receiver.port)).not.toBe(DEFAULT_PORT); expect(Number(receiver.port)).toBeGreaterThan(0); expect(info).toHaveBeenCalledWith( - `The Local daemon is using port ${DEFAULT_PORT}, so this run captures on a free port. Add --session to capture into the daemon instead.`, + `Port ${DEFAULT_PORT} is held by the Local daemon, so this run listens on port ${receiver.port} instead. SDKs that hard-code ${DEFAULT_PORT} won't reach it; make sure they read SENTRY_SPOTLIGHT. Add --session to capture into the daemon instead.`, ); } finally { info.mockRestore();