Skip to content

fix(cli): Don't attach local run or serve to a non-receiver on the port - #2433

Merged
MathurAditya724 merged 1 commit into
mainfrom
fix/local-run-foreign-port
Nov 19, 2026
Merged

MathurAditya724 merged 1 commit into
mainfrom
fix/local-run-foreign-port

Conversation

@sentry-junior

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

Copy link
Copy Markdown
Contributor

If any HTTP server was on the Local port, local run and local serve treated it as a Local receiver. They attached to it, and every event was lost without a word.

Now a server only counts as a receiver if its /health sends the X-Powered-By: spotlight-by-sentry header. Local and Spotlight's own sidecar both send it, even on errors. If anything else holds the port:

  • a plain local run captures on a free port and says so, the same way it does when the Local daemon holds the port
  • local run --port N and local serve stop with a port-in-use error that names the port

Attaching to the daemon, a local serve in another terminal, or the Spotlight sidecar works the same as before.

Before, with python -m http.server 8969 running:

$ sentry local run -- node app.js
[info] Connected to existing server at http://127.0.0.1:8969
[warn] SSE stream returned HTTP 404
[warn] Could not attach to the event stream at http://127.0.0.1:8969/stream

local serve printed the same, then exited 0.

After:

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

$ sentry local serve
Error: Port 8969 is already in use by another process. Stop it, or pass --port to use a different port.

local serve exits non-zero here, and so does local run --port N when N is held.

via @MathurAditya724.

--

View Session [Sentry]

Any HTTP reply to /health counted as an existing receiver, so a port
held by something like `python -m http.server` made `local run` and
`local serve` "connect" to it and lose every event. A receiver is now
recognized by the X-Powered-By header that Local and Spotlight's
sidecar both send. A plain `local run` on a port held by anything else
captures on a free port and says so; an explicit --port and `local
serve` fail with a port-in-use error.

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 19, 2026 6:08pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Nov 19, 2026 6:08pm UTC

Request 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.

Reviewed and retested with main after #2432. Typecheck, lint and the full workspace suite pass. Independent real-HTTP health probes cover seven combinations of foreign/receiver/daemon headers and success/error statuses. Real CLI checks confirm that run and serve fail with exit 21 on an explicit foreign port, while a foreign listener on the default port causes run to capture successfully on another port without posting to the foreign server. Identified sidecars remain attachable on HTTP 503. No actionable findings.

@MathurAditya724
MathurAditya724 merged commit 923a86a into main Nov 19, 2026
33 of 34 checks passed
@MathurAditya724
MathurAditya724 deleted the fix/local-run-foreign-port branch November 19, 2026 19:44
MathurAditya724 added a commit that referenced this pull request Nov 20, 2026
…2437)

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.
```

<!-- junior-request-attribution:start -->
via @MathurAditya724.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3Aa01bd99b1c38568d947d97979a3a64cb -->

--

[View
Session](https://junior-prod.sentry.dev/conversations/agent%3Aa01bd99b1c38568d947d97979a3a64cb)
[[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3Aa01bd99b1c38568d947d97979a3a64cb/?project=4510944073809921)

<!-- junior-session-footer:end -->

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com>

This branch was successfully deployed

1 active and 1 inactive deployments
Preview – cli — 3bedd221 Deployed Nov 19, 2026 by vercel[bot]
Preview – sentry-local — 3bedd221 Deployed Nov 19, 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