Skip to content

fix(cli): Don't attach local run to a port that never answers HTTP - #2437

Merged
MathurAditya724 merged 3 commits into
mainfrom
fix/local-run-unresponsive-port
Nov 20, 2026
Merged

MathurAditya724 merged 3 commits into
mainfrom
fix/local-run-unresponsive-port

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Follow-up to #2433.

#2433 stopped local run and local serve from attaching to an HTTP server that isn't a Local receiver. But if whatever holds the port never sends an HTTP reply to /health, the probe still read that as "nothing here". That covers a silent listener, a slow one, a non-HTTP service or a TLS server. The bind then failed, the CLI attached anyway, and events were lost.

Now only a refused connection means the port is free. Anything else counts as held by another process, so it goes through the same free-port fallback or error that #2433 added. Also in this PR:

  • The probe doesn't follow redirects anymore, so a /health that redirects to a real receiver no longer passes for one.
  • If something takes the port between the probe and the bind, run probes again instead of attaching blindly.
  • --verify uses the same "is held by another process" wording.
  • A local serve from CLI 0.35–0.40 doesn't send the receiver header, so it now counts as another process. Upgrade it to attach to it.

Before, with a silent TCP listener on 8969:

$ sentry local run -- node app.js
[info] No server detected, starting one in the background...
[warn] Port 8969 is in use; attaching to it instead

Every event was lost.

After:

$ sentry local run -- node app.js
[info] Port 8969 is held by another process, so this run listens on port 35735 instead. SDKs that hard-code 8969 won't reach it; make sure they read SENTRY_SPOTLIGHT.

$ sentry local run --port 18771 -- node app.js
Error: Port 18771 is already in use by another process. Stop it, or pass --port to use a different port.

via @MathurAditya724.

--

View Session [Sentry]

The /health probe treated every fetch failure as "nothing there", so a
silent or slow listener, a non-HTTP service, or a TLS server on the port
still got attached and its events were lost. Only a refused connection
now means the port is free; anything else counts as held by another
process. The probe no longer follows redirects, and when the bind loses
a race `local run` probes again instead of attaching blindly.

Co-Authored-By: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com>
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cli Ready Ready Preview Nov 20, 2026 2:48am UTC
1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Nov 20, 2026 2:48am UTC

Request Review

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit c0cbed8. Configure here.

@MathurAditya724 MathurAditya724 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The silent/non-HTTP/TLS/reset/redirect probes behave correctly, but the real CLI reproduces an ephemeral-port startup regression on macOS. Please fix the inline finding before merge.

The /health probe called every connect failure other than a refusal
"unresponsive", so a host that doesn't resolve or an address that isn't
local came back as "port in use by another process". DNS and
unreachable-address failures now count as "nothing there" too, and the
bind reports its own accurate error.

The probe tests now fail like Node's fetch does instead of leaning on
the preload stub's plain Error, so production drops its fallback for
errors that don't come from fetch.

Co-Authored-By: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com>
@MathurAditya724

MathurAditya724 commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Completed review of updated head 30a5858, integrated with the reviewed Local fixes. Full workspace tsc, lint and test passed (13,709 CLI tests). The port-zero finding is fixed and resolved: eight actual run/serve cases passed across localhost/127.0.0.1 on Node 22.17.1 and 24.14.0, including an actual health response and graceful serve shutdown. Real listener probes on both Node versions passed free localhost/IPv4/IPv6 ports, silent TCP, non-HTTP, TLS, reset and redirect refusal. Explicit silent-port rejection and default-8969 fallback also still pass through the actual CLI.

The remaining blocking finding is now the locally fetch-restricted port case, recorded in the new inline review: a free port 6000 gets reported as occupied because Node fetch rejects the URL before connecting (cause.message === "bad port", no code). Raw TCP bind confirms availability; the pre-#2437 CLI binds it and starts the child, while this head exits 21. Please distinguish local fetch policy rejection from an actual peer accepting the connection and add real CLI regression coverage. Review: #2437 (review)

@MathurAditya724 MathurAditya724 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Port-zero is fixed: eight actual run/serve cases passed on Node 22 and 24 with localhost/IPv4, and the listener-health checks still pass. Wider port testing found another confirmed pre-connect classification regression; see inline.

Node's fetch refuses some ports, such as 6000, with "bad port" before it
connects, so the /health probe called a free port held and `local run`
and `local serve` exited with "Port 6000 is already in use". When fetch
fails without a connect error or a timeout, a plain TCP connect now
decides: a port that accepts a connection is still held, any other port
is free and the bind reports any problem.

`--port 0` asks the OS for a port, so the probe skips it.

@MathurAditya724 MathurAditya724 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed and retested f0806e7 integrated with main aae9b4b. Both prior findings are addressed: explicit port zero is not probed, and a local fetch policy rejection uses a bounded TCP connection to distinguish free ports from actual listeners. Checked socket cleanup, IPv6/localhost handling, redirects, silent/non-HTTP/TLS/reset holders, and the bind-race path. No remaining actionable findings.

Full workspace tsc, lint and test passed (13,712 CLI tests, 2,469 MCP core, 483 Cloudflare, 501 Local). Independent Node 22.17.1 and 24.14.0 CLI tests passed 12 run/serve scenarios, including SDK HTTP 200 delivery on ports zero and 6000, graceful shutdown, and occupied-port rejection before spawning the child. Thirty real TCP/HTTP classification cases passed across both Node versions, including IPv4, IPv6 and dual-stack localhost. Default-port fallback and explicit silent-port rejection passed three further real CLI scenarios. Junior's three new end-to-end regression tests also passed. Hosted checks are green on this exact head.

@MathurAditya724
MathurAditya724 merged commit 7c618d5 into main Nov 20, 2026
31 checks passed
@MathurAditya724
MathurAditya724 deleted the fix/local-run-unresponsive-port branch November 20, 2026 03:02

This branch was successfully deployed

1 active and 1 inactive deployments
Preview – cli — f0806e7c Deployed Nov 20, 2026 by vercel[bot]
Preview – sentry-local — f0806e7c Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant