serverless/serverless · critical

panic(err) — downloadFrameworkVersion failure

Error message

panic(err) — downloadFrameworkVersion failure

What it means

In the outer EnsureFrameworkVersion path, downloadFrameworkVersion returned a non-nil error that is NOT context.Canceled (cancellation is handled with a clean exit 130 message just above). The code panics, aborting the launcher with a stack trace. The underlying error is whatever downloadFrameworkVersion produced — most often one of errors 600–606 (extraction/package.json), a network failure from the HTTP fetch, or a `resolving home dir` error from os.UserHomeDir at the top of that function.

Source

Thrown at binary-installer/src/version.go:299

			fmt.Fprintf(os.Stderr, "No version found for %s\n", version)
			os.Exit(1)
		}
		shouldPrintAutoUpdateWarning = matchedVersion.shouldPrintAutoUpdateWarning
		releaseRecord = &ReleaseRecord{
			Version:       FrameworkVersion(matchedVersion.matchedVersion),
			ReleaseDate:   time.Now().Format(time.RFC3339),
			DownloadUrl:   fmt.Sprintf("https://install.serverless.com/archives/serverless-%s.tgz", matchedVersion.matchedVersion),
			LatestVersion: FrameworkVersion(matchedVersion.matchedVersion),
		}
	}

	releasePath, err := downloadFrameworkVersion(releaseRecord, shouldCheckForUpdates, shouldPrintAutoUpdateWarning)
	if err != nil {
		if errors.Is(err, context.Canceled) {
			fmt.Fprintf(os.Stderr, "Installation interrupted\n")
			os.Exit(130)
		}
		panic(err)
	}
	return &FrameworkRelease{
		Version:       releaseRecord.Version,
		ReleasePath:   releasePath,
		LatestVersion: &releaseRecord.LatestVersion,
	}, nil
}

func findClosestMatch(versions []string, constraint string) (string, error) {
	// Parse the constraint
	c, err := semver.NewConstraint(constraint)
	if err != nil {
		return "", fmt.Errorf("invalid constraint: %w", err)
	}

	// Parse and sort the versions
	var semvers semver.Collection
	for _, v := range versions {

View on GitHub (pinned to b9d7ea51c8)

Solutions

1. Re-run the command — many triggers (network blips, transient proxy errors) clear on retry; the launcher resumes from where it can.
2. Clear any partial release before retrying: `rm -rf ~/.serverless/releases/<version>`.
3. Inspect the stderr above the panic for the wrapped error — it points to the real cause (network, disk, package.json).
4. Verify connectivity to install.serverless.com: `curl -I https://install.serverless.com/versions.json`.
5. If $HOME is unset, set it (see errors 608–614).

Example fix

// The panic wraps a real error printed just above it. Recover by clearing state and retrying:
rm -rf ~/.serverless/releases/<version>
curl -fsSL https://install.serverless.com/versions.json | head   # confirm reachability
serverless <command>

// Pre-flight before invoking serverless in automation:
func installPreflight() error {
  if err := homeReady(); err != nil { return err }            // see 608
  resp, err := http.Head("https://install.serverless.com/versions.json")
  if err != nil || resp.StatusCode/100 != 2 {
    return fmt.Errorf("install.serverless.com unreachable")
  }
  return nil
}

null

null

When it happens

Trigger: Triggered after downloadFrameworkVersion fails for any reason other than user-initiated cancellation: network error fetching the .tgz from install.serverless.com, gzip/tar read error, any of the extraction errors (600/601/602), archiveHasDependencies failure (603/605/606), or npm install failure (604). Because the caller does not retry, a transient network blip becomes a hard panic.

Common situations: Flaky networks where the .tgz download fails partway; corporate proxies blocking install.serverless.com; the underlying extraction/permission errors from 600–606 propagating up; first-time installs on misconfigured systems. The panic is user-visible and not actionable without re-running.

Related errors

• INVALID_CONFIGURATION
• ACM_CERTIFICATE_VALIDATION_TIMEOUT
• AWS_WAF_INVALID_ACL_ARN
• Invalid response from CloudFront KV Store creation
• writing temp installer %s: %w

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/4e53bc343c281b95. Report an issue: GitHub.