thedotmack/claude-mem · error

Failed to install uv. Please install manually

Error message

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

What it means

installUv wraps any failure from runUvInstaller into an actionable error with platform-specific manual install instructions (winget/astral.sh PowerShell on Windows; curl/brew otherwise) plus the underlying error from describeExecError, so users can install uv by hand.

Solutions

  1. Install uv manually with the commands in the error message (curl -LsSf https://astral.sh/uv/install.sh | sh, winget, or brew).
  2. Restart your terminal so uv is on PATH, then re-run the installer.
  3. Read the 'Underlying error' line to fix the root cause (proxy, DNS, permissions) first.

Example fix

// before
npx claude-mem install   # uv installer download fails
// after
brew install uv   # macOS fallback, then re-run installer
Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

try {
  await ensureUv();
} catch (e) {
  console.error(String(e)); // includes manual install commands and underlying cause
  // offer: exec('curl -LsSf https://astral.sh/uv/install.sh | sh')
}

Prevention

When it happens

Trigger: runUvInstaller throws — network failure downloading the astral.sh installer, non-zero exit, timeout, or missing curl/sh on the system.

Common situations: Air-gapped or proxied environments, missing curl in slim Docker images, Windows without winget, or Homebrew not present on macOS.

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/ec03fb4b53924846. Report an issue: GitHub.

Appendix: source

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

    });
  }

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

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

/**
 * Subpath imports the bundled worker requires transitively (via
 * @modelcontextprotocol/sdk / @anthropic-ai/claude-agent-sdk). A stale/partial
 * install can leave the `zod` directory present while these subpath exports fail
 * to resolve — surfacing later as a runtime `Cannot find module 'zod/v3'`. We
 * assert them at install time so a broken closure fails LOUD here. Version-agnostic:
 * we resolve subpaths, never a pinned version.
 */
const ZOD_REQUIRED_SUBPATHS = ['zod/v3', 'zod/v4', 'zod/v4-mini'] as const;

export function verifyCriticalModules(targetDir: string): void {
  const pkg = JSON.parse(readFileSync(join(targetDir, 'package.json'), 'utf-8'));

View on GitHub (pinned to d8bc9755e7)