Failed to install uv. Please install manually: ${manualInstr

Error message

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

What it means

Thrown by installUv() when runUvInstaller() throws — the uv installer script failed (network, timeout, non-zero exit) or the post-install binary check failed (error 36). It wraps the underlying error with platform-specific manual uv install instructions and the describeExecError() dump. Symmetric to error 35 for uv. When the user has opted out of vector search, this path is bypassed and a WARN_CONTINUE is recorded instead.

Source

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

    });
  }

  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 d768ba3643)

Solutions

Follow the manual instructions in the error: install uv via winget/brew/curl/pip into a PATH dir, then re-run.
Configure HTTP(S)_PROXY for the install if network is filtered.
If the 'Underlying error' shows a timeout, retry on a faster connection or raise INSTALL_TIMEOUT_MS.
If you do not need vector search, enable the vector-search opt-out so uv becomes optional and this ABORT is avoided.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  installUv();
} catch (e) {
  if (e instanceof Error && /Failed to install uv/.test(e.message)) {
    if (userHasOptedOutOfVectorSearch()) { /* continue without uv */ }
    else { /* prompt manual install */ }
  }
  throw e;
}

Prevention

Pre-install uv (winget/brew/pip) on PATH in restricted networks.
Configure HTTP(S)_PROXY for astral.sh reachability.
Opt out of vector search in environments where uv cannot be installed.

When it happens

Trigger: curl cannot reach astral.sh (offline/proxy/firewall). The uv install script exits non-zero. INSTALL_TIMEOUT_MS exceeded. /bin/sh unavailable for the pipe. Post-install isUvInstalled() fails (error 36) and propagates here. Corporate proxy rewriting the script.

Common situations: Air-gapped CI. Slow networks hitting the install timeout. Proxy environments that block astral.sh. Locked-down Windows shells.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/ec03fb4b53924846. Report an issue: GitHub.