Skip to content

fix(cli): Make installer failures actionable - #2286

Merged
BYK merged 5 commits into
mainfrom
fix/cli-installer-unexpected-failures
Nov 16, 2026
Merged

BYK merged 5 commits into
mainfrom
fix/cli-installer-unexpected-failures

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Fixes CLI-BJ (https://sentry.sentry.io/issues/7314884676/).

CLI-BJ collects every Unexpected failure at line N event from the bash installer's ERR trap. This PR first makes the installer recover from the failures behind those events. It dies with a clearer message only when the user has to act, and it keeps reporting the failures that are left.

Prevention and recovery

  • Network retries. Every curl call (registry, GitHub releases, GHCR token/manifest/blob, downloads) now passes --retry 3 --retry-connrefused --retry-max-time 60. curl retries timeouts, refused connections, 408, 429, and 5xx with exponential backoff. The binary needs glibc 2.28 or macOS 11, whose curl (7.61, 7.64) has --retry-connrefused (7.52) but not --retry-all-errors (7.71), so --retry-all-errors is not used. The 2s --max-time probe in report_error is unchanged.
  • Broken or corrupt downloads. download_verified downloads once more when the transfer breaks, the SHA-256 does not match, or gunzip -t rejects the archive. If the .gz is missing or still unusable, it falls back to the raw binary as before. A checksum mismatch on both tries is still fatal. install.ps1 also downloads once more on a mismatch, because both installers share the scenario table.
  • Full or unwritable temp directory (the 7 events still firing at line 434/436). When a write into $TMPDIR fails (curl exit 23, or gunzip cannot write), the installer stages the file in the directory setup installs into. This covers stable and nightly downloads. It resolves that directory the same way as determineInstallDir in src/lib/binary.ts, and matches PATH entries like samePath: one trailing slash is ignored, and on macOS and Windows so is case. The binary takes setup's own temp name, <install-dir>/sentry.download, so sentry cli setup --install renames it into place atomically instead of copying it. The nightly GHCR fetch reads its response headers from stdout, so only the body needs disk space. Partial files are removed. The installer prints "There is not enough room to stage sentry ..." only when both directories fail.
  • GitHub rate limits (the old ~25.9k-event group, mostly bash 5.2 on Ubuntu 24.04, probably CI runners). When the registry is unreachable, the releases fallback sends Authorization: Bearer $GITHUB_TOKEN (or GH_TOKEN) if one is set. The header goes to curl on stdin (-H @-), so the token is not in the process list. Because $BASH_COMMAND is unexpanded source text, an error report shows ${token}, not the value. Responses with 403/429 are retried after 2s and 4s. Without a token, the installer suggests setting GITHUB_TOKEN. GitHub Actions does not export GITHUB_TOKEN automatically, so workflows need env: GITHUB_TOKEN: ${{ github.token }}.
  • Unreadable registry body (5 events, line 305/307, Windows bash only). The body and status now come from curl's stdout (-w '\n%{http_code}') instead of a temp file that bash sometimes could not read. Why bash could not read the file is not confirmed.

Reporting

  • set -E, and the trap goes through on_unexpected_failure. It reports the line, the function, the exit status, and $BASH_COMMAND, truncated to 200 chars. $BASH_COMMAND is unexpanded source text ("$tmp_binary", not the path), so reports contain no user paths, env values, or tokens. No new tags or fields; only the message text changes. Before this, a failure inside a function exited 1 with no message and no report. On bash 3.2, the line number pointed at the closing fi of the enclosing block (the 1 event at line 442).
  • report_error runs trap - ERR in its subshell, so an offline ingest cannot set off the trap again.
  • Hash tool failures are now checked inside checksum_matches. It runs as a condition, where the ERR trap is off, and it dies with a checksum step.

The older groups (no events since Oct 1, pre-Toolkit script ≤0.45.0) are already fixed on main: ~25.9k events from the GitHub releases/latest lookup (lines 281/280/304), 101 from sentry cli setup exits (lines 333/332), and 128 from the raw curl with no || die (lines 302/304/394/398/400).

Before / after

Real runs of the main installer and this branch in a sandbox. curl, gunzip, and the network are stubbed per case; <install-dir> is a placeholder.

Full temp directory during unpack:

before: gzip: stdout: No space left on device
        Unexpected failure at line 436
        exit=1  reported: {"message": "Unexpected failure at line 436", "step": "trap"}
after:  gzip: stdout: No space left on device
        Not enough room in the temporary directory; using <install-dir> instead.
        setup ok
        exit=0  reported: (nothing)

Release registry returns 503 twice, then 200 (real curl 8.x against a local server):

before: Could not resolve latest from Sentry's release registry. Trying GitHub...
        Failed to list Toolkit releases
        exit=1
after:  Downloading sentry v0.49.0...
        setup ok
        exit=0

Connection reset on the first .gz and the first raw download:

before: curl: (56) Recv failure: Connection reset by peer
        Failed to download https://github.com/getsentry/toolkit/releases/download/cli@0.49.0/sentry-linux-x64
        exit=1  reported: {"step": "download"}
after:  curl: (56) Recv failure: Connection reset by peer
        The download of sentry-linux-x64.gz was incomplete or corrupt. Downloading it again...
        setup ok
        exit=0  reported: (nothing)

Truncated first .gz (checksum mismatch):

before: Checksum mismatch for sentry-linux-x64 0.49.0: expected 01887b09…, got 80f75ffb…
        exit=1  reported: {"step": "checksum"}
after:  The download of sentry-linux-x64.gz was incomplete or corrupt. Downloading it again...
        setup ok
        exit=0  reported: (nothing)

Registry down, GitHub returns 403 once:

before: curl: (22) The requested URL returned error: 403
        Failed to list Toolkit releases
        exit=1  reported: {"step": "gh-version"}
after:  GitHub rate-limited the request; retrying in 2s...
        Downloading sentry v0.49.0...
        setup ok
        exit=0  reported: (nothing)

Unexpected failure that is still reported (chmod fails):

before: Unexpected failure at line N
after:  Unexpected failure at line N (exit 1): chmod +x "$tmp_binary"

via @betegon, @BYK.

--

View Session [Sentry]

Fixes CLI-BJ. The installer's ERR trap reported only "Unexpected failure at
line N", and bash 3.2 reports the closing `fi` of the enclosing block, so
the line often pointed nowhere. A failure inside a function exited with no
message and no report, because the ERR trap was not inherited.

- Enable errtrace and report the failing command's unexpanded source text,
  its function, and its exit status. The text has no expanded paths or
  values.
- Stop report_error from tripping the trap on its own failures.
- Give a failed gunzip, usually a full temporary directory, a clear message
  and its own `unpack` step.
- Read release registry metadata from curl's stdout instead of a temp file,
  which bash could not read on some Windows shells.

Co-Authored-By: bete <28983162+betegon@users.noreply.github.com>
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

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

1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Nov 16, 2026 10:29am UTC

Request Review

@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 16, 2026

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

Stale Bugbot comment from a previous run.

Comment thread packages/cli/install Resolved
The redirected nightly path still piped curl into gunzip, so a full temp
directory there hit the generic trap. Download to the blob file first and
unpack it like the other paths.
Retry transient network errors with curl's backoff, download a broken or
corrupt archive once more, stage the download in the install directory
when the temp directory is full or unwritable, and authenticate the GitHub
releases fallback with GITHUB_TOKEN or GH_TOKEN, retrying rate limits.
install.ps1 also downloads once more on a checksum mismatch, since both
installers share the scenario table.

Refs CLI-BJ

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
CodeQL flagged the api.github.com substring check.

@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 3 potential issues.

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 6e272dc. Configure here.

Comment thread packages/cli/install Resolved
Comment thread packages/cli/install Resolved
…e setup

Nightly GHCR fetches now go through write_staged, with the response
headers read from stdout instead of a temp file, and a write failure
dies with the no-room message. The install-dir PATH check ignores one
trailing slash, and case on macOS and Windows, like samePath, so the
staged binary lands where setup renames it.
@BYK
BYK merged commit fcc022a into main Nov 16, 2026
35 checks passed
@BYK
BYK deleted the fix/cli-installer-unexpected-failures branch November 16, 2026 10:59

This branch was previously deployed

1 inactive deployment
Preview — 2d9aae19 Deployed Nov 16, 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.

3 participants