# How Chat-MCP Handles Electron Mirror and Installation Timeout Issues

> Discover how Chat-MCP tackles Electron mirror and installation timeouts. Learn strategies like environment variable configuration, cache clearing, and client initialization timeouts for smoother builds.

- Repository: [AIQL/chat-mcp](https://github.com/ai-ql/chat-mcp)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Chat-MCP mitigates Electron download failures and installation stalls by configuring the `ELECTRON_MIRROR` environment variable, clearing local caches when builds fail, and enforcing a 30-second timeout on client initialization in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts).**

The open-source Chat-MCP project depends on Electron and electron-builder, which download binaries exceeding 100 MB during installation and packaging. In regions where the default Electron download server is slow or blocked, `npm install` can stall indefinitely, often after the `node_modules` folder reaches approximately 300 MB. The repository implements three complementary strategies to ensure reliable builds and startup across network-constrained environments.

## Configuring the Electron Mirror Environment Variable

The primary defense against slow or unreachable Electron downloads is redirecting requests to an alternative CDN using the **`ELECTRON_MIRROR`** environment variable. Electron’s installer scripts automatically read this variable, requiring no code changes within the project.

As documented in the README under the *Installation timeout* section, setting this variable to a reachable mirror—such as Tsinghua University’s CDN—allows the install to complete without hitting the default server.

Set the mirror in your shell before running `npm install`:

```bash

# Bash / Zsh

export ELECTRON_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/electron/"
npm install

```

On Windows (PowerShell), use:

```powershell
$env:ELECTRON_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/electron/"
npm install

```

## Clearing Stale Electron and Electron-Builder Caches

When **electron-builder** encounters download interruptions or corrupted partial files, subsequent builds may fail repeatedly. The project recommends manually clearing the local Electron and electron-builder caches to force a fresh download from the configured mirror.

According to the README’s *Electron builder timeout* section, delete these directories before retrying:

- `C:\Users\<USERNAME>\AppData\Local\electron`
- `C:\Users\<USERNAME>\AppData\Local\electron-builder`

Use this PowerShell command to remove both cache folders:

```powershell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron-builder"

```

## Enforcing a 30-Second Client Initialization Timeout

Beyond installation issues, Chat-MCP prevents runtime hangs by enforcing a strict timeout during client startup. In [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts), the application races the `initializeClient` function against a **`timeoutPromise`** that rejects after 30 seconds.

This guard ensures that any client failing to initialize—whether due to network latency or misconfiguration—does not block the UI indefinitely. The implementation appears at lines 64-70 of [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts):

```typescript
const timeoutPromise = new Promise<Client>((resolve, reject) => {
  setTimeout(() => {
    reject(new Error(`Initialization of client for ${name} timed out after 30 seconds`));
  }, 30_000);
});

const client = await Promise.race([
  initializeClient(name, serverConfig),
  timeoutPromise,
]);

```

If the initialization exceeds 30 seconds, the promise rejects with a diagnostic error, causing the app to exit cleanly rather than hanging.

## Summary

- **Redirect downloads** by setting `ELECTRON_MIRROR` to a regional CDN before installation to bypass slow or blocked default servers.
- **Clear caches** at `AppData/Local/electron` and `AppData/Local/electron-builder` when electron-builder timeouts persist, ensuring fresh downloads.
- **Guard runtime startup** with a 30-second timeout in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) to prevent client initialization from blocking the application indefinitely.

## Frequently Asked Questions

### What causes Electron installation timeouts in Chat-MCP?

Electron binaries are approximately 100 MB and are downloaded during both `npm install` and electron-builder packaging. In regions with restricted or slow access to the default Electron download server, the transfer can stall, particularly after significant progress when the `node_modules` folder reaches roughly 300 MB.

### How do I configure a mirror for Electron downloads in Chat-MCP?

Set the **`ELECTRON_MIRROR`** environment variable to a trusted CDN URL, such as `https://mirrors.tuna.tsinghua.edu.cn/electron/`, before executing `npm install`. Electron’s built-in installer scripts detect this variable automatically and fetch binaries from the specified mirror instead of the default host.

### Where does Chat-MCP implement the initialization timeout?

The 30-second timeout is implemented in **[`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts)** (lines 64-70). The code creates a `timeoutPromise` that rejects after 30,000 milliseconds and races it against the `initializeClient` function using `Promise.race`, ensuring the application exits with an error if startup hangs.

### Why should I clear the Electron cache when builds fail?

Corrupted or incomplete downloads in the local Electron or electron-builder caches can cause repeated installation failures, even after configuring a working mirror. Deleting the cache folders forces the build tools to download fresh binaries from the currently configured mirror, resolving issues caused by stale or partial files.