Activity

1. james-tindal

   added

   pending triage

   on Oct 30, 2026
2. james-tindal

   added the

   Bug

   issue type on Oct 30, 2026
3. voidzero-bot commented on Oct 30, 2026

   

   voidzero-botBot

   on Oct 30, 2026

   Contributor

   More actions

   • Reproduced: Yes
   • Exploration: Yes — View branch
   • Unit Test: Yes — crates/vp_js_runtime/src/runtime.rs::test_download_runtime_missing_platform_archive
   • Priority: P2: Has Workaround. This breaks node/npm/pnpm/bun shims for darwin-x64 users who have Node v27.0.0-alpha.0.0.0 as their default, but the user can work around it by switching to a different default Node version (e.g. vp env default lts).

   The root cause is in crates/vp_js_runtime/src/runtime.rs: download_runtime_with_provider constructs the platform archive name for the requested Node.js version, downloads SHASUMS256.txt, and asks NodeProvider::parse_shasums for the hash. When the release omits a tarball for the host platform (as v27.0.0-alpha.0.0.0 does for darwin-x64), parse_shasums returns Error::HashNotFound, which surfaces as the cryptic "Hash not found" message.

   I found a potential fix for this issue. The patch adds a new MissingPlatformArchive error variant in crates/vp_js_runtime/src/error.rs and maps the HashNotFound case to it in download_runtime_with_provider, producing a message like node v27.0.0-alpha.0.0.0 does not provide a darwin-x64 archive (...); this version may not be available for your platform. It also adds a regression test and updates the existing lock-release test. The vp_js_runtime test suite passes, but please review before merging.

   Full Triage Report

   Triage Report: Issue #3290 — Executables throwing

   Issue Summary

   Reporter: james-tindal
   Title: Executables throwing
   System: macOS (darwin-x64), vp v1.4.0, managed Node.js v27.0.0-alpha.0.0.0 from default config.

   The reporter states that running node, npm, pnpm, or bun through Vite+ shims fails with:

   vp: Failed to install Node 27.0.0-alpha.0.0.0: Hash not found for node-v27.0.0-alpha.0.0.0-darwin-x64.tar.gz in SHASUMS256.txt
   

   Expected behavior: Vite+ should either install the requested runtime or produce a clear error explaining that the platform tarball is unavailable. Actual behavior: the commands crash with a low-level "Hash not found" message.

   Environment Used for Reproduction

   • Host: Linux x86_64 (GitHub Actions runner)
   • Vite+ checkout: /home/runner/work/vite-plus/vite-plus
   • Vite+ version: vp v1.4.0 (local build from checkout)
   • Node.js (system): v24.22.1
   • pnpm: v12.11.2
   • Fresh isolated VP_HOME: /tmp/vite-plus-triage/gh-3290/vp-home

   Reproduction Steps

   1. Installed the local CLI into an isolated VP_HOME:

      VP_HOME=/tmp/vite-plus-triage/gh-3290/vp-home pnpm install-global-cli

   2. Set the default Node.js version to the same alpha version reported:

      export VP_HOME=/tmp/vite-plus-triage/gh-3290/vp-home
      $VP_HOME/bin/vp env default 27.0.0-alpha.0.0.0

   3. Confirmed vp env current resolves to the alpha version with Source default:

      Node.js:
        Version    27.0.0-alpha.0.0.0
        Source     default
        Installed  false
        Mode       managed
      

   4. The Linux x64 tarball for v27.0.0-alpha.0.0.0 exists on nodejs.org, so the bug does not reproduce on the bare Linux runner. To reproduce the same SHASUMS "Hash not found" failure path, a local mirror was started that serves a valid index containing v27.0.0-alpha.0.0.0 but a SHASUMS256.txt that omits the current platform tarball.

   5. With the mirror configured, all four reported executables fail identically:

      export VP_NODE_DIST_MIRROR=http://localhost:8765
      node -v
      npm -v
      pnpm -v
      bun -v

      Output for each:

      vp: Failed to install Node 27.0.0-alpha.0.0.0: Hash not found for node-v27.0.0-alpha.0.0.0-linux-x64.tar.gz in SHASUMS256.txt
      

   Verification of the Underlying Cause

   • nodejs.org/dist/v27.0.0-alpha.0.0.0/SHASUMS256.txt contains node-v27.0.0-alpha.0.0.0-darwin-arm64.tar.gz but does not contain node-v27.0.0-alpha.0.0.0-darwin-x64.tar.gz.
   • On a darwin-x64 machine (the reporter's host), VP therefore downloads a valid SHASUMS file, fails to find the expected platform archive in it, and surfaces the HashNotFound error from crates/vp_js_runtime/src/error.rs.
   • On Linux x64 the tarball exists, so the same default version installs successfully.

   Control Case

   Removing the custom mirror and deleting the cached alpha runtime causes VP to download node-v27.0.0-alpha.0.0.0-linux-x64.tar.gz from nodejs.org successfully:

   v27.0.0-alpha.0.0.0
   12.1.0
   12.16.1
   1.4.4
   

   This confirms the failure is tied to the missing platform archive in the SHASUMS file, not to the alpha version string itself.

   Result

   Reproduced. The reported behavior occurs on the current checkout when the Node.js distribution's SHASUMS file does not include a tarball for the current platform. The reporter's darwin-x64 host hits this condition for v27.0.0-alpha.0.0.0 because Node.js shipped that alpha without a darwin-x64 archive. Vite+ should provide a clearer message (e.g., "Platform tarball not available for Node X on platform Y") instead of the current "Hash not found" error.

   ---

   Diagnosis

   Affected Code Path

   1. Version resolution (exact version bypass)
      crates/vp_global_cli/src/commands/env/config.rs:539-556 — resolve_version_string sees 27.0.0-alpha.0.0.0 as an exact semver version and returns it verbatim. It never checks whether Node.js actually publishes a tarball for the current platform.

   2. Shim dispatch
      crates/vp_global_cli/src/shim/dispatch.rs:826-844 — resolve_with_cache returns the alpha version from the default config, then ensure_installed tries to download it. Errors are surfaced as vp: Failed to install Node {version}: {error}.

   3. Runtime download / hash lookup
      crates/vp_js_runtime/src/runtime.rs:184-208 (download_runtime_with_provider) constructs the platform archive name via provider.get_download_info(version, platform), fetches SHASUMS256.txt, and calls provider.parse_shasums(...).

   4. SHASUMS parser
      crates/vp_js_runtime/src/providers/node.rs:688-700 — NodeProvider::parse_shasums returns Error::HashNotFound { filename: ... } as soon as the expected platform filename is absent from the SHASUMS file.

   Root Cause

   NodeProvider unconditionally builds the URL/filename for the current platform (node-v{version}-{platform}.{ext}) and then asks the SHASUMS file for its hash. If the Node.js release lists other platform tarballs but omits the one for the host platform, the first indication of the problem is the cryptic HashNotFound error. For v27.0.0-alpha.0.0.0, the release includes darwin-arm64 but not darwin-x64, so every darwin-x64 user with this default version sees the reported failure on every shim invocation.

   The message is especially confusing because:

   • The version does exist (index.json contains it).
   • The SHASUMS file does download successfully.
   • Only after parsing do we discover the platform archive is missing, and the error text sounds like a corrupted hash file rather than a missing platform build.

   Suggested Fix

   Add an explicit "missing platform archive" error path in download_runtime_with_provider. After parse_shasums returns Error::HashNotFound for the expected archive filename, map it to a new Error variant (or reuse/extend UnsupportedPlatform) that mentions the version, the platform string, and the missing filename:

   Node.js v27.0.0-alpha.0.0.0 does not provide a darwin-x64 archive
   (node-v27.0.0-alpha.0.0.0-darwin-x64.tar.gz)
   

   Implementation options:

   1. Minimal change in crates/vp_js_runtime/src/runtime.rs
      Wrap the parse_shasums call inside download_runtime_with_provider. On Error::HashNotFound, return a new Error::MissingPlatformArchive { version, platform, filename } or an improved UnsupportedPlatform that includes the version. This requires only the platform string already available at that call site.

   2. Add a new error variant in crates/vp_js_runtime/src/error.rs
      Example:

      #[error("Node.js v{version} does not provide a {platform} build ({filename}); \
              this version may not be available for your platform")]
      MissingPlatformArchive { version: Str, platform: Str, filename: Str },

      This gives callers (shim dispatch, vp env install, etc.) a clear, actionable message without network overhead.

   3. (Optional) Pre-check index.json#files
      The Node.js version index includes a files array per release. NodeProvider could check that array before constructing download info. This is a nice early-exit but is less robust than option 1 because custom mirrors may not populate files the same way, whereas the SHASUMS file is authoritative for what can actually be downloaded.

   Edge Cases

   • Custom mirrors / unofficial builds: A mirror might publish SHASUMS256.txt without all platform entries. The SHASUMS-based check covers this automatically.
   • Future Node.js releases: Node.js sometimes drops or renames platform artifacts (e.g., osx-x64-pkg vs. darwin-x64). The fix stays correct as long as it relies on the actual SHASUMS content.
   • Cached installations: ensure_installed only enters the download path when the binary is not already cached, so the new error only affects fresh installs.

   Regression Evidence

   No existing test asserts the missing-platform-tarball case. crates/vp_js_runtime/src/providers/node.rs has test_parse_shasums for successful lookups, and crates/vp_js_runtime/src/runtime.rs uses with_mock_mirror for happy-path downloads, but neither exercises a SHASUMS that omits the host platform. A regression test should serve a mock index containing the version and a SHASUMS without the expected archive, then assert the improved error message.

   Confidence

   High. The failure was reproduced on the current checkout using a local mirror that serves a valid index but a SHASUMS missing the host-platform tarball; all four reported tools (node, npm, pnpm, bun) emit the exact same Hash not found chain, and code inspection shows the only place the message originates is NodeProvider::parse_shasums.

   ---

   Verification

   Claim

   When the Node.js release for the resolved version does not include a tarball for the current platform, Vite+ shims fail with:

   vp: Failed to install Node 27.0.0-alpha.0.0.0: Hash not found for node-v27.0.0-alpha.0.0.0-darwin-x64.tar.gz in SHASUMS256.txt
   

   The reporter expects a clear indication that the platform build is unavailable. Vite+ currently surfaces a low-level hash lookup failure instead.

   Research

   • Documentation: docs/guide/env.md describes managed mode and version resolution but does not document any intentional behavior around missing platform tarballs or "Hash not found" errors.
   • Prior issue: gh issue view 771 in voidzero-dev/vite-plus is titled Failed to download Node.js 20: Hash not found for node-v20-linux-x64.tar.gz in SHASUMS256.txt and was labeled as a Bug before being closed. This establishes that the project treats this error surface as a bug, not expected behavior.
   • Code intent: crates/vp_js_runtime/src/error.rs defines an UnsupportedPlatform error variant, indicating the codebase already reserves a distinct error path for platform-related failures. That variant is currently unused for the missing-tarball case.
   • Tests: No existing test asserts that a missing platform archive should produce "Hash not found"; the SHASUMS parser tests only cover successful lookups (crates/vp_js_runtime/src/providers/node.rs, test_parse_shasums).

   Verdict

   Bug.

   Reasoning

   • The message "Hash not found" is technically accurate (the expected filename is absent from SHASUMS256.txt) but semantically misleading: it suggests a corrupted or incomplete hash file rather than a missing platform build.
   • Vite+ has a dedicated UnsupportedPlatform error path, implying that platform availability problems should be reported separately.
   • A prior issue with the same error text was classified as a bug by the maintainers.
   • The behavior contradicts the expected user experience: a user who selects an available-looking Node version should see a clear "this version is not available for your platform" message, not a hash lookup failure.

   Confidence

   High. Direct evidence comes from the prior bug classification (#771), the unused platform-specific error variant, and the absence of any documentation or test asserting that "Hash not found" is the intended UX for a missing platform archive.

   ---

   Fix

   Decision

   Fixed. The bug was reproduced with high-confidence diagnosis and the root cause was clear and local to Vite+. No product decision or upstream change is needed.

   Implementation

   Changed files

   1. crates/vp_js_runtime/src/error.rs

      • Added new error variant MissingPlatformArchive { runtime, version, platform, filename } with a user-facing message explaining that the runtime version exists but does not provide an archive for the current platform.

   2. crates/vp_js_runtime/src/runtime.rs

      • In download_runtime_with_provider, when provider.parse_shasums returns Error::HashNotFound for the expected archive filename, map it to Error::MissingPlatformArchive using the runtime name, requested version, current platform string, and archive filename.
      • Updated the existing test_failed_download_releases_installation_lock test to expect MissingPlatformArchive (an empty SHASUMS now surfaces the missing-archive error).
      • Added regression test test_download_runtime_missing_platform_archive that serves a Node.js index containing v27.0.0-alpha.0.0.0 but a SHASUMS256.txt that omits the host platform tarball, asserting the new error variant is returned.

   Rationale

   The previous behavior correctly detected that the expected filename was absent from the SHASUMS file, but it surfaced a generic HashNotFound error. That message is misleading because the problem is not a corrupted hash file; it is that the Node.js release does not ship a tarball for the user's platform. Vite+ already had an UnsupportedPlatform error variant, indicating the codebase distinguishes platform-related failures. A dedicated MissingPlatformArchive variant produces a clear, actionable message without adding extra network requests.

   Validation

   Regression test

   cargo test -p vp_js_runtime test_download_runtime_missing_platform_archive

   Result: test runtime::tests::test_download_runtime_missing_platform_archive ... ok

   Crate test suite

   cargo test -p vp_js_runtime

   Result: test result: ok. 136 passed; 0 failed; 0 ignored

   Build/check

   cargo check -p vp_js_runtime
   cargo check -p vp_global_cli

   Both passed.

   Original reproduction (after fix)

   Using the same isolated VP_HOME with default Node.js 27.0.0-alpha.0.0.0 and a local mirror whose SHASUMS omits the host platform tarball:

   Before fix:

   vp: Failed to install Node 27.0.0-alpha.0.0.0: Hash not found for node-v27.0.0-alpha.0.0.0-linux-x64.tar.gz in SHASUMS256.txt
   

   After fix:

   vp: Failed to install Node 27.0.0-alpha.0.0.0: node v27.0.0-alpha.0.0.0 does not provide a linux-x64 archive (node-v27.0.0-alpha.0.0.0-linux-x64.tar.gz); this version may not be available for your platform
   

   All four reported tools (node, npm, pnpm, bun) now surface the improved message.

   Control case

   Removing the mirror and clearing the cache restores normal behavior; VP downloads node-v27.0.0-alpha.0.0.0-linux-x64.tar.gz from nodejs.org and the tools execute successfully:

   v27.0.0-alpha.0.0.0
   12.1.0
   12.16.1
   1.4.4
   

   Skipped checks

   • cargo fmt --all --check: skipped because rustfmt is not installed for the active nightly toolchain (nightly-2026-08-02).
   • cargo clippy -p vp_js_runtime: skipped because clippy is not installed for the active nightly toolchain.
   • The changes are small and localized; the existing cargo check and focused test suite pass.

   Alternatives considered

   • Pre-check index.json#files before downloading: would add an early exit but is less robust for custom mirrors and requires fetching/understanding per-release file lists.
   • Reuse the existing UnsupportedPlatform variant: that variant implies the platform is unsupported for the runtime in general, whereas the issue is version-specific (the current platform is supported, but this particular release omits its tarball).
   • Issue a HEAD request to the archive URL to distinguish "missing archive" from "missing hash": adds latency and an extra network round trip; the SHASUMS content is authoritative for what the release contains.

   git diff

   M crates/vp_js_runtime/src/error.rs
   M crates/vp_js_runtime/src/runtime.rs

   See the full diff in the checkout.

   This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

   I've opened a pull request with this fix: #3291
4. voidzero-bot

   added

   triage: fix verified

   - P2: has workaroundAffects specific usage and has a straightforward workaround (priority)Affects specific usage and has a straightforward workaround (priority)

   on Oct 30, 2026
5. naokihaba

   self-assigned this

   on Nov 4, 2026
6. naokihaba commented on Nov 8, 2026

   

   naokihaba

   on Nov 8, 2026

   Last edited by naokihaba

   Collaborator

   More actions

   @james-tindal
   Thanks for reporting this! In v1.4.0, the Node.js latest alias was resolving to the 27.0.0-alpha.0.0.0 pre-release, which caused the shims to fail because it lacks a darwin-x64 archive.

   We've fixed this in #3335 so that latest points to the latest stable release instead. The fix is included in v1.5.0, so could you upgrade and give it another try?

   vp upgrade
   vp env current
7. james-tindal commented on Nov 8, 2026

   

   james-tindal

   on Nov 8, 2026

   Author

   More actions

   Yeah that's working well now. Thanks!

   ❤️React with ❤️1Reacted by NaokiHaba
8. naokihaba

   closed this as not plannedon Nov 9, 2026
9. naokihaba

   closed this as completedon Nov 9, 2026