fix(install): surface real mirror download failures

Stop remapping every failed archive/checksum attempt to ""not found"". Keep the detailed error for total mirror failure; log light skips when a later mirror succeeds.

Refs #1401

Co-authored-by: Cursor 

Author: coreybutler

src/installer/download_error.go

@@ -0,0 +1,48 @@
+package installer
+
+import (
+	nvmhttp "common/http"
+	"fmt"
+	"net/http"
+	"strings"
+)
+
+func describeDownloadResultFailure(label, url string, result nvmhttp.DownloadResult) error {
+	if result.Error != nil {
+		return fmt.Errorf("%s %s: %w", label, url, result.Error)
+	}
+	if result.Response == nil || result.Response.Response == nil {
+		return fmt.Errorf("%s %s: empty response", label, url)
+	}
+	status := result.Response.Response.StatusCode
+	statusText := strings.TrimSpace(result.Response.Response.Status)
+	if statusText == "" {
+		statusText = http.StatusText(status)
+	}
+	if status == http.StatusNotFound {
+		return fmt.Errorf("%s %s: HTTP %s (missing on this mirror)", label, url, statusText)
+	}
+	return fmt.Errorf("%s %s: HTTP %s", label, url, statusText)
+}
+
+func formatNodeMirrorDownloadFailure(version, archiveName string, mirrors []string, lastErr error) error {
+	mirrorNote := "configured mirror"
+	if len(mirrors) > 1 {
+		mirrorNote = fmt.Sprintf("%d configured mirrors", len(mirrors))
+	}
+	if lastErr == nil {
+		return fmt.Errorf(
+			"failed to download Node.js v%s (%s) from %s",
+			version,
+			archiveName,
+			mirrorNote,
+		)
+	}
+	return fmt.Errorf(
+		"failed to download Node.js v%s (%s) from %s: %w",
+		version,
+		archiveName,
+		mirrorNote,
+		lastErr,
+	)
+}

src/installer/download_error_test.go

@@ -0,0 +1,59 @@
+package installer
+
+import (
+	nvmhttp "common/http"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestDescribeDownloadResultFailureTransport(t *testing.T) {
+	err := describeDownloadResultFailure("archive", "https://example/a.7z", nvmhttp.DownloadResult{
+		Error: errors.New("context deadline exceeded"),
+	})
+	if err == nil || !strings.Contains(err.Error(), "context deadline exceeded") {
+		t.Fatalf("error = %v", err)
+	}
+	if !strings.Contains(err.Error(), "archive https://example/a.7z") {
+		t.Fatalf("error = %v, want label+url", err)
+	}
+}
+
+func TestDescribeDownloadResultFailureHTTPStatus(t *testing.T) {
+	res := &http.Response{StatusCode: http.StatusNotFound, Status: "404 Not Found"}
+	err := describeDownloadResultFailure("checksum", "https://example/SHASUMS256.txt", nvmhttp.DownloadResult{
+		Response: &nvmhttp.DownloadResponse{Response: res},
+	})
+	if err == nil || !strings.Contains(err.Error(), "HTTP 404 Not Found") {
+		t.Fatalf("error = %v", err)
+	}
+	if !strings.Contains(err.Error(), "missing on this mirror") {
+		t.Fatalf("error = %v, want missing hint", err)
+	}
+}
+
+func TestFormatNodeMirrorDownloadFailureWrapsCause(t *testing.T) {
+	err := formatNodeMirrorDownloadFailure("24.20.0", "node-v24.20.0-win-x64.7z", []string{"https://nodejs.org/dist"}, errors.New("timeout"))
+	got := err.Error()
+	for _, want := range []string{
+		"failed to download Node.js v24.20.0",
+		"node-v24.20.0-win-x64.7z",
+		"configured mirror",
+		"timeout",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("error = %q, want substring %q", got, want)
+		}
+	}
+	if strings.Contains(got, "not found on server/mirror") {
+		t.Fatalf("legacy misleading message still present: %q", got)
+	}
+}
+
+func TestFormatNodeMirrorDownloadFailurePluralMirrors(t *testing.T) {
+	err := formatNodeMirrorDownloadFailure("22.0.0", "node-v22.0.0-win-x64.7z", []string{"a", "b"}, nil)
+	if !strings.Contains(err.Error(), "2 configured mirrors") {
+		t.Fatalf("error = %q", err)
+	}
+}

src/installer/installer.go

@@ -402,6 +402,7 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 	if !fromCache && !cfg.LocalOnly {
 		downloaded := false
 		var downloadEnd time.Time
+		var lastDownloadErr error
 		insecure := allowInsecureDownloads(cfg)
 		mirrors := settings.Global().NodeMirror
 		singleMirror := len(mirrors) == 1
@@ -422,6 +423,8 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 			shasumURI := fmt.Sprintf("%s/v%s/SHASUMS256.txt", mirror, version)
 			shasumJob, err := http.Download(shasumURI, http.DownloadConfig{Cache: true, Destination: shasumPath, AllowInsecure: insecure})
 			if err != nil {
+				lastDownloadErr = fmt.Errorf("checksum %s: %w", shasumURI, err)
+				log.Logf("mirror %s skipped for v%s: %v", mirror, version, lastDownloadErr)
 				continue
 			}
 
@@ -438,6 +441,12 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 							return authErr
 						}
 					}
+					if ok {
+						lastDownloadErr = describeDownloadResultFailure("checksum", shasumURI, result)
+					} else {
+						lastDownloadErr = fmt.Errorf("checksum %s: download closed unexpectedly", shasumURI)
+					}
+					log.Logf("mirror %s skipped for v%s: %v", mirror, version, lastDownloadErr)
 					continue
 				}
 			}
@@ -446,12 +455,16 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 			normalizedURI, err := http.NormalizeURL(uri)
 			if err != nil {
 				_ = os.Remove(shasumPath)
+				lastDownloadErr = fmt.Errorf("archive %s: %w", uri, err)
+				log.Logf("mirror %s skipped for v%s: %v", mirror, version, lastDownloadErr)
 				continue
 			}
 
 			job, err := http.Download(normalizedURI, http.DownloadConfig{Destination: target, AllowInsecure: insecure})
 			if err != nil {
 				_ = os.Remove(shasumPath)
+				lastDownloadErr = fmt.Errorf("archive %s: %w", normalizedURI, err)
+				log.Logf("mirror %s skipped for v%s: %v", mirror, version, lastDownloadErr)
 				continue
 			}
 
@@ -470,7 +483,7 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 					}
 				case result, ok := <-job.Result:
 					if !ok {
-						downloadErr = fmt.Errorf("download closed unexpectedly")
+						downloadErr = fmt.Errorf("archive %s: download closed unexpectedly", normalizedURI)
 						break downloadLoop
 					}
 					if result.Error != nil || result.Response == nil || !result.Response.Success {
@@ -480,7 +493,7 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 								break downloadLoop
 							}
 						}
-						downloadErr = fmt.Errorf("download error")
+						downloadErr = describeDownloadResultFailure("archive", normalizedURI, result)
 						break downloadLoop
 					}
 					downloadEnd = time.Now()
@@ -498,6 +511,8 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 					status.Downloads--
 					return downloadErr
 				}
+				lastDownloadErr = downloadErr
+				log.Logf("mirror %s skipped for v%s: %v", mirror, version, lastDownloadErr)
 				continue
 			}
 
@@ -521,7 +536,7 @@ func downloadNode(ctx context.Context, version, target string, cfg InstallConfig
 
 		if !downloaded {
 			status.Downloads--
-			return fmt.Errorf("Node.js v%s not found on server/mirror", version)
+			return formatNodeMirrorDownloadFailure(version, archiveName, mirrors, lastDownloadErr)
 		}
 
 		if logf != nil {