From 176789499abc008666bb9163e89c80f42cf25ade Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:11:07 +0000 Subject: [PATCH 1/3] fix(cli): Exit 124 when local run --timeout stops the app When `--timeout` stopped the app, `local run` exited with whatever the app returned on SIGTERM: 143 with an error for most apps, 137 after a SIGKILL escalation, and 0 for apps such as `next dev`, so a timeout looked like success. Exit 124 whenever the timeout stops the app, as GNU `timeout` does, and print one line instead of an error. An app that exits first keeps its code, and `--verify` timeouts still exit 64. Co-Authored-By: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com> --- apps/cli-docs/src/content/docs/exit-codes.md | 1 + apps/cli-docs/src/fragments/commands/local.md | 4 ++ .../skills/sentry-cli/references/local.md | 2 +- packages/cli/src/commands/local/run.ts | 10 +++- packages/cli/src/lib/errors.ts | 3 ++ packages/cli/test/commands/local/run.test.ts | 48 ++++++++++++++----- 6 files changed, 53 insertions(+), 15 deletions(-) diff --git a/apps/cli-docs/src/content/docs/exit-codes.md b/apps/cli-docs/src/content/docs/exit-codes.md index b3beeaedd..c0f7a8709 100644 --- a/apps/cli-docs/src/content/docs/exit-codes.md +++ b/apps/cli-docs/src/content/docs/exit-codes.md @@ -45,6 +45,7 @@ react to failure categories without parsing stderr. | 51 | Device Flow Error | OAuth device authorization flow failed | | 60 | Output Error | Command produced output but the operation failed | | 64 | Verify Failed | `sentry local run --verify` received no events from the SDK | +| 124 | Run Timeout | `sentry local run --timeout` stopped the app (the GNU `timeout` convention) | | 252 | Invalid Argument | An argument could not be parsed — see [Argument errors](#argument-errors) | ## Scripting Examples diff --git a/apps/cli-docs/src/fragments/commands/local.md b/apps/cli-docs/src/fragments/commands/local.md index a40d0a970..f0e4b0101 100644 --- a/apps/cli-docs/src/fragments/commands/local.md +++ b/apps/cli-docs/src/fragments/commands/local.md @@ -44,6 +44,10 @@ The `` variants put the URL where your bundler can inline it into browse When `local run` sees `wrangler dev` and a `wrangler.json`, `wrangler.jsonc`, or `wrangler.toml`, it also adds `--var SENTRY_SPOTLIGHT:`, because Wrangler does not pass process env vars to Worker code. An explicit `--var SENTRY_SPOTLIGHT:...` is kept. No project file is changed. +### Stop after a set time with `--timeout` + +`sentry local run --timeout -- ` stops your app after that many seconds and exits 124, as GNU `timeout` does, whatever exit code the app gives when it stops. If the app exits on its own first, `local run` exits with the app's code. + ### Check your setup with `--verify` `sentry local run --verify -- ` starts your app, waits for its first event, then stops it. It exits 0 once an event arrives. It fails if the app exits, crashes, or sends nothing within the timeout (30 seconds, or `--timeout `). When port 8969 is busy, it verifies on a free port. diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/local.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/local.md index b648fa4bc..8079869e9 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/local.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/local.md @@ -193,7 +193,7 @@ Run a command with the local dev server enabled - `--host - Hostname for the local server - (default: "localhost")` - `-f, --filter ... - Only show items of this type (repeatable: error, transaction, log, ai)` - `-V, --verify - Verify SDK sends events, then exit` -- `-t, --timeout - Kill the child after N seconds (0 = no timeout; defaults to 30 s in --verify mode) - (default: "0")` +- `-t, --timeout - Stop the child after N seconds and exit 124 (0 = no timeout; defaults to 30 s in --verify mode, which exits 64) - (default: "0")` - `-F, --format - Output format: human (default) or json (NDJSON on stdout) - (default: "human")` - `-a, --attributes - Also show SDK attributes, under each transaction, span and log or in JSON` - `--open - Open Sentry Local UI in the browser` diff --git a/packages/cli/src/commands/local/run.ts b/packages/cli/src/commands/local/run.ts index 3e0586f03..23d1fa7af 100644 --- a/packages/cli/src/commands/local/run.ts +++ b/packages/cli/src/commands/local/run.ts @@ -592,7 +592,7 @@ export const runCommand = buildCommand({ kind: "parsed", parse: textParser(parseTimeout), brief: - "Kill the child after N seconds (0 = no timeout; defaults to 30 s in --verify mode)", + "Stop the child after N seconds and exit 124 (0 = no timeout; defaults to 30 s in --verify mode, which exits 64)", default: "0", }, format: { @@ -766,7 +766,6 @@ export const runCommand = buildCommand({ let timeoutId: ReturnType | undefined; if (flags.timeout > 0) { timeoutId = setTimeout(() => { - logger.warn(`Timeout: killing child after ${flags.timeout}s`); interruptState.timedOut = true; void gracefulKill(child, ownGroup); }, flags.timeout * 1000); @@ -811,6 +810,13 @@ export const runCommand = buildCommand({ } } + // How the app ends once --timeout stops it depends on the app (0, 143, + // 137, ...), so report the timeout itself. + if (interruptState.timedOut) { + logger.info(`Stopped after ${flags.timeout}s (--timeout)`); + this.process.exitCode = EXIT.RUN_TIMEOUT; + return; + } const exitCode = exit.signal ? signalExitCode(exit.signal) : (exit.code ?? EXIT.GENERAL); diff --git a/packages/cli/src/lib/errors.ts b/packages/cli/src/lib/errors.ts index d5b0f7b63..5b96580aa 100644 --- a/packages/cli/src/lib/errors.ts +++ b/packages/cli/src/lib/errors.ts @@ -105,6 +105,9 @@ export const EXIT = { OUTPUT_ERROR: 60, /** `sentry local run --verify` received no events from the SDK */ VERIFY_FAILED: 64, + + /** `sentry local run --timeout` stopped the app, as GNU `timeout` exits */ + RUN_TIMEOUT: 124, } as const; /** diff --git a/packages/cli/test/commands/local/run.test.ts b/packages/cli/test/commands/local/run.test.ts index c657437f0..8fc8312e8 100644 --- a/packages/cli/test/commands/local/run.test.ts +++ b/packages/cli/test/commands/local/run.test.ts @@ -898,26 +898,50 @@ setInterval(() => {}, 1000); }); }); - test("--timeout kills the child after N seconds", async () => { - const func = (await runCommand.loader()) as unknown as RunFunc; - const ctx = makeContext(); - - // "sleep 60" would take too long — timeout at 1s should kill it + test.each([ + { app: "dies from SIGTERM", args: ["sleep", "60"] }, + { + app: "exits 0 on SIGTERM", + args: [ + process.execPath, + "-e", + "process.on('SIGTERM', () => process.exit(0)); setInterval(() => {}, 1000);", + ], + }, + ])("--timeout exits 124 when it stops an app that $app", async ({ args }) => { + const info = vi.spyOn(logger, "info").mockImplementation(() => {}); try { + const func = (await runCommand.loader()) as unknown as RunFunc; + const ctx = { ...makeContext(), process: { exitCode: undefined } }; await func.call( ctx, { port: 0, host: "127.0.0.1", verify: false, timeout: 1 }, - "sleep", - "60", + ...(args as [string, ...string[]]), ); - expect.unreachable("should have thrown"); - } catch (err) { - expect(err).toBeInstanceOf(CliError); - // The child is killed by SIGTERM, resulting in a non-zero exit - expect((err as CliError).message).toContain("exited with code"); + expect(ctx.process.exitCode).toBe(EXIT.RUN_TIMEOUT); + expect(info.mock.calls.map((c) => String(c[0]))).toContain( + "Stopped after 1s (--timeout)", + ); + } finally { + info.mockRestore(); } }); + test("--timeout keeps the exit code of an app that exits first", async () => { + const func = (await runCommand.loader()) as unknown as RunFunc; + const error = await func + .call( + makeContext(), + { port: 0, host: "127.0.0.1", verify: false, timeout: 10 }, + process.execPath, + "-e", + "process.exit(3)", + ) + .catch((err: unknown) => err); + expect(error).toBeInstanceOf(CliError); + expect((error as CliError).exitCode).toBe(3); + }); + test("--verify with a quick-exit process throws VERIFY_FAILED", async () => { const func = (await runCommand.loader()) as unknown as RunFunc; const ctx = makeContext(); From 52d2a261545e58e58f4271498b36d030de7ec125 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 19:06:10 +0000 Subject: [PATCH 2/3] fix(cli): Leave a Ctrl-C shutdown alone when --timeout fires MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit If the user already stopped the app and it is still shutting down when the --timeout timer fires, let it finish and keep its exit code instead of exiting 124. Print "Stopping after Ns (--timeout)…" when the timer fires, so an app that ignores SIGTERM isn't silent until the SIGKILL. List 124 and 252 as shell conventions in the exit code ranges. Co-Authored-By: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com> --- apps/cli-docs/src/content/docs/exit-codes.md | 2 + packages/cli/src/commands/local/run.ts | 6 ++ packages/cli/src/lib/errors.ts | 2 +- packages/cli/test/commands/local/run.test.ts | 66 +++++++++++++++++--- 4 files changed, 66 insertions(+), 10 deletions(-) diff --git a/apps/cli-docs/src/content/docs/exit-codes.md b/apps/cli-docs/src/content/docs/exit-codes.md index c0f7a8709..3a9ba85ad 100644 --- a/apps/cli-docs/src/content/docs/exit-codes.md +++ b/apps/cli-docs/src/content/docs/exit-codes.md @@ -18,6 +18,8 @@ react to failure categories without parsing stderr. | 40–49 | Feature | Feature availability and billing issues | | 50–59 | Operations | Upgrade and OAuth flow errors | | 60–69 | Command | Command-specific non-standard exits | +| 124 | Shell convention | `sentry local run --timeout` stopped the app, as GNU `timeout` exits | +| 252 | Shell convention | An argument could not be parsed | ## Complete Reference diff --git a/packages/cli/src/commands/local/run.ts b/packages/cli/src/commands/local/run.ts index 23d1fa7af..1091707af 100644 --- a/packages/cli/src/commands/local/run.ts +++ b/packages/cli/src/commands/local/run.ts @@ -766,6 +766,12 @@ export const runCommand = buildCommand({ let timeoutId: ReturnType | undefined; if (flags.timeout > 0) { timeoutId = setTimeout(() => { + // The user already stopped the app, so it is shutting down: let it + // finish and keep its exit code. + if (interruptState.interrupted) { + return; + } + logger.info(`Stopping after ${flags.timeout}s (--timeout)…`); interruptState.timedOut = true; void gracefulKill(child, ownGroup); }, flags.timeout * 1000); diff --git a/packages/cli/src/lib/errors.ts b/packages/cli/src/lib/errors.ts index 5b96580aa..dcc8bd198 100644 --- a/packages/cli/src/lib/errors.ts +++ b/packages/cli/src/lib/errors.ts @@ -77,7 +77,7 @@ export const EXIT = { // 30–39: API & network (HTTP 502/503/504 family) /** Sentry API returned an error */ API: 30, - /** Operation timed out */ + /** API operation timed out */ TIMEOUT: 31, /** Rate limited by the Sentry API — wait before retrying */ RATE_LIMITED: 32, diff --git a/packages/cli/test/commands/local/run.test.ts b/packages/cli/test/commands/local/run.test.ts index 8fc8312e8..b8995af8e 100644 --- a/packages/cli/test/commands/local/run.test.ts +++ b/packages/cli/test/commands/local/run.test.ts @@ -674,6 +674,26 @@ setInterval(() => {}, 1000); }, ); + test("keeps the app's exit code when --timeout fires during a Ctrl-C shutdown", async () => { + const ctx = { ...makeContext(), process: { exitCode: undefined } }; + const func = (await runCommand.loader()) as unknown as RunFunc; + const ready = join(tmpDir, "ready"); + // Takes 1.5s to shut down after SIGINT, so --timeout 1 fires meanwhile. + const run = func.call( + ctx, + { port: 0, host: "127.0.0.1", verify: false, timeout: 1 }, + process.execPath, + "-e", + `process.on("SIGINT", () => setTimeout(() => process.exit(0), 1500));require("node:fs").writeFileSync(${JSON.stringify(ready)}, "");setInterval(() => {}, 1000);`, + ); + await vi.waitFor(async () => { + await readFile(ready, "utf8"); + }); + signals.send("SIGINT"); + await expect(run).resolves.toBeUndefined(); + expect(ctx.process.exitCode).toBeUndefined(); + }, 20_000); + describe("with an app behind a wrapper that ignores SIGINT", () => { /** * Like `go run`: ignores SIGINT, dies from SIGTERM without passing it @@ -755,21 +775,21 @@ app.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 1))); } }, 30_000); - test("--timeout leaves no app running", async () => { + test("--timeout leaves no app running and exits 124", async () => { const { wrapper, appPidFile } = await wrappedApp(); const warn = vi.spyOn(logger, "warn").mockImplementation(() => {}); try { const func = (await runCommand.loader()) as unknown as RunFunc; - await func - .call( - makeContext(), - { port: 0, host: "127.0.0.1", verify: false, timeout: 2 }, - process.execPath, - wrapper, - ) - .catch(() => undefined); + const ctx = { ...makeContext(), process: { exitCode: undefined } }; + await func.call( + ctx, + { port: 0, host: "127.0.0.1", verify: false, timeout: 2 }, + process.execPath, + wrapper, + ); const pid = await appPid(appPidFile); expect(isRunning(pid)).toBe(false); + expect(ctx.process.exitCode).toBe(EXIT.RUN_TIMEOUT); } finally { warn.mockRestore(); } @@ -927,6 +947,27 @@ setInterval(() => {}, 1000); } }); + test("--timeout exits 124 when the app ignores SIGTERM and gets SIGKILL", async () => { + const info = vi.spyOn(logger, "info").mockImplementation(() => {}); + try { + const func = (await runCommand.loader()) as unknown as RunFunc; + const ctx = { ...makeContext(), process: { exitCode: undefined } }; + await func.call( + ctx, + { port: 0, host: "127.0.0.1", verify: false, timeout: 1 }, + process.execPath, + "-e", + "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);", + ); + expect(ctx.process.exitCode).toBe(EXIT.RUN_TIMEOUT); + const lines = info.mock.calls.map((c) => String(c[0])); + expect(lines).toContain("Stopping after 1s (--timeout)…"); + expect(lines).toContain("Stopped after 1s (--timeout)"); + } finally { + info.mockRestore(); + } + }, 20_000); + test("--timeout keeps the exit code of an app that exits first", async () => { const func = (await runCommand.loader()) as unknown as RunFunc; const error = await func @@ -965,6 +1006,7 @@ setInterval(() => {}, 1000); test("--verify with --timeout throws on timeout", async () => { const func = (await runCommand.loader()) as unknown as RunFunc; const ctx = makeContext(); + const info = vi.spyOn(logger, "info").mockImplementation(() => {}); try { await func.call( @@ -978,6 +1020,12 @@ setInterval(() => {}, 1000); expect(err).toBeInstanceOf(VerifyFailedError); expect((err as CliError).message).toContain("Verification timed out"); expect((err as CliError).exitCode).toBe(64); + // The --verify timeout is not the plain-run --timeout. + expect( + info.mock.calls.some((c) => String(c[0]).includes("(--timeout)")), + ).toBe(false); + } finally { + info.mockRestore(); } }); From ae93851069de9d59b25ef85e9992608720938dd8 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 19:20:45 +0000 Subject: [PATCH 3/3] test(cli): Pass the ready file path to the test app as an argument --- packages/cli/test/commands/local/run.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/cli/test/commands/local/run.test.ts b/packages/cli/test/commands/local/run.test.ts index b8995af8e..2b8f14c58 100644 --- a/packages/cli/test/commands/local/run.test.ts +++ b/packages/cli/test/commands/local/run.test.ts @@ -684,7 +684,9 @@ setInterval(() => {}, 1000); { port: 0, host: "127.0.0.1", verify: false, timeout: 1 }, process.execPath, "-e", - `process.on("SIGINT", () => setTimeout(() => process.exit(0), 1500));require("node:fs").writeFileSync(${JSON.stringify(ready)}, "");setInterval(() => {}, 1000);`, + // The ready file path comes in as an argument, not inside the code. + 'process.on("SIGINT", () => setTimeout(() => process.exit(0), 1500));require("node:fs").writeFileSync(process.argv[1], "");setInterval(() => {}, 1000);', + ready, ); await vi.waitFor(async () => { await readFile(ready, "utf8");