Failed to install Bun. Please install manually

Error message

Failed to install Bun. Please install manually:
${manualInstructions}
Then restart your terminal and try again.
Underlying error: ${describeExecError(err)}

What it means

installBun wraps any failure from runBunInstaller into a single actionable error listing platform-specific manual install instructions (winget/PowerShell on Windows, curl/brew otherwise) plus the underlying error from describeExecError. It exists so users can fall back to a manual Bun install when the automated one fails.

Solutions

Install Bun manually using the commands printed in the error (winget/powershell on Windows; curl script or brew otherwise).
Restart your terminal so PATH includes bun, then re-run the installer.
Inspect the 'Underlying error' line for the root cause (DNS, timeout, permission) and fix network/proxy issues.

Example fix

// before
npx claude-mem install   # automated bun install fails behind proxy
// after
export HTTPS_PROXY=http://proxy:8080
curl -fsSL https://bun.sh/install | bash   # or fix proxy and re-run

Defensive patterns

Strategy: try-catch

Validate before calling

const hasNetwork = await fetch('https://bun.sh', { method: 'HEAD' }).then(() => true).catch(() => false);
if (!hasNetwork) console.warn('Skipping automated bun install; install manually.');

Try / catch

try {
  await ensureBun();
} catch (e) {
  console.error(String(e)); // message already contains manual install steps
  // offer: exec('curl -fsSL https://bun.sh/install | bash')
}

Prevention

Check network/proxy reachability to bun.sh before automated installs.
Preinstall bun in Docker images and CI to avoid runtime downloads.
Keep winget/brew/curl available on target machines.
Read the 'Underlying error' section before retrying.

When it happens

Trigger: runBunInstaller throws — download failure, network error, unsupported platform shell, installer script non-zero exit, or timeout (INSTALL_TIMEOUT_MS exceeded).

Common situations: Corporate proxy/firewall blocking bun.sh, no network access, Windows without winget, or curl unavailable in minimal containers.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/be2099a5f7f41912. Report an issue: GitHub.

Appendix: source

Thrown at src/npx-cli/install/setup-runtime.ts:215

    });
  }

  if (!isBunInstalled()) {
    throw new Error(
      'Bun installation completed but binary not found. Please restart your terminal and try again.',
    );
  }
}

function installBun(): void {
  try {
    runBunInstaller();
  } catch (error) {
    const err = error instanceof Error ? error : new Error(String(error));
    const manualInstructions = IS_WINDOWS
      ? '  - winget install Oven-sh.Bun\n  - Or: powershell -c "irm bun.sh/install.ps1 | iex"'
      : '  - curl -fsSL https://bun.sh/install | bash\n  - Or: brew install oven-sh/bun/bun';
    throw new Error(
      `Failed to install Bun. Please install manually:\n${manualInstructions}\nThen restart your terminal and try again.\n` +
        `Underlying error: ${describeExecError(err)}`,
    );
  }
}

/** Run the platform-specific uv installer, then confirm the binary is resolvable. */
function runUvInstaller(): void {
  if (IS_WINDOWS) {
    execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', {
      stdio: 'pipe',
      timeout: INSTALL_TIMEOUT_MS,
      shell: process.env.ComSpec ?? 'cmd.exe',
    });
  } else {
    execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', {
      stdio: 'pipe',
      timeout: INSTALL_TIMEOUT_MS,

View on GitHub (pinned to d8bc9755e7)