fix: override yauzl to 3.3.1 to fix Electron postinstall hang on Node 24.16.0+ by jeremeioss · Pull Request #3584 · nexu-io/open-design

jeremeioss · 2026-06-03T17:02:12Z

Discovered while testing linux appimage build as part of this closed issue
Reported in this comment

Why

Running pnpm tools-pack linux build --to appimage on Node ≥ 24.16.0 fails
with:

⨯ ENOENT: no such file or directory, rename '.../builder/linux-unpacked/electron'
  -> '.../builder/linux-unpacked/Open Design'

electron-builder tries to rename the extracted Electron binary, but it
doesn't exist because Electron's postinstall silently produced a broken
runtime: electron/dist/ contains only v8_context_snapshot.bin — no binary,
no locales/, no resources/. The postinstall script exits 0 with no error or
warning.

Root cause

Electron's install.js uses extract-zip → yauzl → fd-slicer to extract
the downloaded binary zip. fd-slicer@1.1.0 implements its own destroy() on
ReadStream, dating back to before Node 8 added a native Readable.destroy().
These two implementations collide with a stream-lifecycle change introduced in
Node 24.16.0 (nodejs/node#63487).

When zlib.createInflateRaw() applies backpressure during decompression, Node
24's stream internals interact with fd-slicer's broken destroy in a way that
prevents the Readable from ever resuming. The raw stream stops after exactly 3
read operations (196,608 / 204,997 bytes), and inflation stalls at 97% (694,688
/ 715,208 bytes). No error event, no close event, no rejection — a silent hang.

This was confirmed by testing each layer in isolation: fs.createReadStream →
InflateRaw works fine; fd-slicer ReadStream → PassThrough works fine;
fd-slicer ReadStream → InflateRaw hangs. The issue is specific to custom
JavaScript Readables with async _read piped into zlib on Node ≥ 24.16.0.

Why a pnpm override

yauzl@3.3.1 ([thejoshwolfe/yauzl#170]) fixes this by dropping fd-slicer
entirely — it only depends on pend. However, extract-zip@2.0.1 (used by
Electron's installer) pins yauzl@^2.10.0 and has been unmaintained for 6 years
(max-mapper/extract-zip#154), so the fix cannot flow through normal dependency
resolution. A pnpm override is the same approach used by VS Code
(microsoft/vscode#318682) and other projects hitting the same issue.

What users will see

No visible UI change. Users building the packaged app on Node ≥ 24.16.0 will
find that pnpm tools-pack linux build (and the equivalent macOS/Windows
paths) now complete successfully instead of silently producing a broken Electron
runtime.

Surface area

UI — new page / dialog / panel / menu item / setting / empty state in apps/web or apps/desktop (including Electron menu bar)
Keyboard shortcut — new or changed
CLI / env var — new od subcommand or flag, new tools-dev / tools-pack / tools-pr flag, or new OD_* env var
API / contract — new /api/* endpoint, new SSE event, or changed shape in packages/contracts
Extension point — new entry under skills/, design-systems/, design-templates/, or craft/, or change to the skills protocol
i18n keys — added new translation keys (see TRANSLATIONS.md for the locale workflow)
New top-level dependency — adding any new entry to the root package.json (dependencies or devDependencies); workspace-package package.json files are out of scope. Include a paragraph on what we get vs. what bytes we ship (see CONTRIBUTING.md → Code style)
Default behavior change — changes what existing users experience without opting in (default model, default setting, file/SQLite schema, auto-network on startup, auto-install)
None — internal refactor, docs, tests, or translation update only

New top-level dependency note: This is not a new dependency — it is a pnpm
override that forces all transitive yauzl resolution to the fixed 3.3.1.
No new package enters the dependency tree; existing yauzl@2.10.0 instances
(from extract-zip → yauzl) are replaced in-place.

Screenshots

Not applicable — no UI change.

Bug fix verification

The bug is a silent hang in a transitive dependency during postinstall, which
is not easily reproducible in a unit test. Verification was done by:

Confirming electron/dist/ is empty (only v8_context_snapshot.bin) on
Node 24.16.0 without the override.
Applying the override, running pnpm install, and confirming electron/dist/
now contains the full runtime (binary, locales/, resources/,
libffmpeg.so, etc.).
Running pnpm tools-pack linux build --to appimage end-to-end successfully.

Validation

pnpm install                        # apply override, verify Electron installs correctly
pnpm guard                          # no new .js/.mjs/.cjs outside allowlist
pnpm typecheck                      # no type errors

…Node 24.16.0+ fd-slicer's custom destroy() collides with Node 24.16.0's stream lifecycle change, causing extract-zip to silently hang at 97% during Electron binary extraction. yauzl 3.x drops fd-slicer entirely. extract-zip is unmaintained and pins yauzl ^2.10.0, so the fix can only flow through a pnpm override. Refs: thejoshwolfe/yauzl#170, nodejs/node#63487

jeremeioss · 2026-06-03T17:04:31Z

@lefarcen this is the PR discussed here

lefarcen · 2026-06-03T17:13:04Z

Hey @jeremeioss, that's the one — and the writeup is exceptional. The layer-by-layer isolation (fs → InflateRaw works, fd-slicer → PassThrough works, fd-slicer → InflateRaw hangs) plus the cites to nodejs/node#63487, yauzl#170, and the VS Code precedent make the yauzl@3.3.1 override choice cleanly justified. The note that extract-zip has been unmaintained for 6 years also closes off the obvious "why not upstream the fix" question.

Routed to @nettee from the review pool. Labeled size/S · risk/high · type/bugfix — risk/high because this is a root-dependency resolution change that affects Electron postinstall behavior, so worth a second pair of eyes before merge. CI is green and lines up with your verification notes.

nettee

@jeremeioss I verified that this override stays aligned with the current dependency graph: in this lockfile it only replaces Electron's extract-zip -> yauzl path, removes fd-slicer from that install chain, and keeps the package metadata and lockfile changes consistent for the Node 24 postinstall fix. Thanks for tracking down a subtle transitive dependency failure and keeping the remediation tight.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

github-actions · 2026-06-04T03:17:52Z

Visual regression review

Head: 467b7b1 · Base: f3ec496

13 changed · 4 unchanged · 0 missing baseline · 0 failed

Changed cases

Case	Main	PR	Diff
visual-design-systems
visual-home
visual-home-catalog
visual-home-context-picker
visual-home-plugin-filter
visual-integrations
visual-integrations-use-everywhere
visual-new-project-modal
visual-plugins
visual-projects
visual-projects-kanban
visual-tasks
visual-topbar-execution-switcher

Unchanged cases

Case	Main	PR	Diff
visual-avatar-menu
visual-plugin-details
visual-settings-byok
visual-settings-execution

Visual diff is advisory only and does not block merging.

open-design-bot · 2026-06-04T04:11:33Z

🎉 📡 You just leveled up to Giotto

📡 ✨ Sending steady signals.

🙌 Your contributions send a clear signal across the network: you care about making Open Design better.

💛 Thanks for helping Open Design move forward. Keep building in the open. 🚀

📊 Rank #198 among 198 contributors.

🔗 Share on X (English) · 分享到 X（中文）

kokisanai · 2026-06-10T03:43:04Z

Hi @jeremeioss!

Your first Open Design PR has been merged! Huge thanks for jumping in and improving the project!

You contributed:

Merged PR: #3584 fix: override yauzl to 3.3.1 to fix Electron postinstall hang on Node 24.16.0+
#3584

You fixed a packaging/install reliability problem at the dependency layer, which is exactly the sort of low-visibility work that saves people from painful setup failures. That makes you a strong fit for other desktop and install-adjacent cleanup.

For your next contribution, we picked two issues that look like a good follow-up:

macOS 15: Open Design icon appears oversized in Launchpad and Dock #1751 macOS 15: Open Design icon appears oversized in Launchpad and Dock
macOS 15: Open Design icon appears oversized in Launchpad and Dock #1751

This stays in the desktop packaging/distribution surface and is a concrete user-facing fix with a clear reproduction area.

Sync and display CLI-installed MCP and Skill for unified management #1838 Sync and display CLI-installed MCP and Skill for unified management
Sync and display CLI-installed MCP and Skill for unified management #1838

This is another install/management-adjacent task that benefits from comfort around app packaging and local environment behavior.

If one of these looks interesting, feel free to comment /claim on the issue and we will help you get started!

Once your second PR gets merged, you will move into our Continuous Contributor tier. We are also starting to highlight repeat contributors more actively in the community, so this is a great time to keep going!

Thanks again for the first PR, and welcome to the Open Design contributor community!

The Open Design team

P.S. We hang out in Discord — come say hi: https://discord.gg/3C6EWXbdQQ
There's a #contributors channel where folks share what they're working on.

lefarcen added size/S PR changes 20-100 lines risk/high High risk: apps/desktop, daemon, auth, migration, workflows, package deps type/bugfix Bug fix labels Jun 3, 2026

lefarcen requested a review from nettee June 3, 2026 17:12

nettee approved these changes Jun 3, 2026

View reviewed changes

Siri-Ray added this pull request to the merge queue Jun 4, 2026

Merged via the queue into nexu-io:main with commit aea4042 Jun 4, 2026
16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: override yauzl to 3.3.1 to fix Electron postinstall hang on Node 24.16.0+#3584

fix: override yauzl to 3.3.1 to fix Electron postinstall hang on Node 24.16.0+#3584
Siri-Ray merged 1 commit into
nexu-io:mainfrom
jeremeioss:fix/electron-postinstall-node24

jeremeioss commented Jun 3, 2026

Uh oh!

jeremeioss commented Jun 3, 2026

Uh oh!

lefarcen commented Jun 3, 2026

Uh oh!

nettee left a comment

Uh oh!

github-actions Bot commented Jun 4, 2026

Uh oh!

Uh oh!

open-design-bot Bot commented Jun 4, 2026

Uh oh!

kokisanai commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

jeremeioss commented Jun 3, 2026

Why

Root cause

Why a pnpm override

What users will see

Surface area

Screenshots

Bug fix verification

Validation

Uh oh!

jeremeioss commented Jun 3, 2026

Uh oh!

lefarcen commented Jun 3, 2026

Uh oh!

nettee left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 4, 2026

Visual regression review

Changed cases

Uh oh!

Uh oh!

open-design-bot Bot commented Jun 4, 2026

🎉 📡 You just leveled up to Giotto

Uh oh!

kokisanai commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants