# How to Fix Electron Builder Timeout Issues During Packaging

> Resolve Electron builder timeout issues during packaging. Set ELECTRON_MIRROR, clear cache, and use a standard terminal for successful builds. Learn how to fix build failures now.

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

---

**Set the `ELECTRON_MIRROR` environment variable to a regional CDN, clear the local Electron cache directories, and execute the build from a standard terminal to eliminate timeout failures during the packaging process.**

The `ai-ql/chat-mcp` repository packages its desktop application using **Electron Builder**, which downloads large Electron binaries from GitHub during the `npm run build-app` step. When network connections are unstable or GitHub's servers are unreachable, these downloads stall and trigger **Electron builder timeout** errors that prevent successful packaging.

## Understanding Why Electron Builder Times Out

During the `build-app` script execution defined in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json) (lines 14-15), Electron Builder reads the configuration in lines 16-50 and downloads platform-specific Electron binaries to the user's local cache. By default, it fetches these from `https://github.com/electron/electron/releases/download/`, which can be slow or blocked in certain regions. If a download is interrupted, the corrupted partial file remains in the cache, causing subsequent builds to fail immediately with timeout errors rather than attempting a fresh download.

## Solution 1: Configure a Regional Electron Mirror

The most effective fix is to redirect Electron Builder to a faster mirror using the **ELECTRON_MIRROR** environment variable before running the build.

On Linux or macOS (Bash):

```bash
export ELECTRON_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/electron/"
npm run build-app

```

On Windows (PowerShell):

```powershell
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm run build-app

```

As documented in the README (lines 78-81 and 182-186), this bypasses GitHub's default servers and routes the download through regional CDNs like Tencent or Alibaba mirrors that offer better connectivity.

## Solution 2: Clear the Corrupted Electron Cache

Stale or incomplete downloads in the local cache must be deleted to force a fresh fetch. According to the troubleshooting section in [`README.md`](https://github.com/ai-ql/chat-mcp/blob/main/README.md) (lines 186-188), remove these directories on Windows:

```cmd
rd /s /q "%LOCALAPPDATA%\electron"
rd /s /q "%LOCALAPPDATA%\electron-builder"
npm run build-app

```

On macOS or Linux, the cache resides in `~/.cache/electron` and `~/.cache/electron-builder`.

## Solution 3: Avoid VS Code's Integrated Terminal

The repository documentation (lines 188-189) specifically recommends running the build from a standard **Command Prompt**, **PowerShell**, or **Terminal** rather than VS Code's integrated terminal. The integrated environment sometimes lacks the necessary permissions to clear cache directories or properly handle the environment variables required for mirror configuration.

## Solution 4: Skip the RPM Target on Debian/Ubuntu

The RPM packaging target can trigger additional network calls that compound timeout issues. For Debian or Ubuntu users, modify the `linux.target` array in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json) (lines 38-43) to exclude the RPM format:

```json
"linux": {
  "target": [
    "AppImage",
    "deb"
  ],
  "icon": "icon.png"
}

```

This configuration is noted in the README (lines 40-44) as a way to streamline the build process and avoid unnecessary external dependencies.

## Complete Clean-and-Build Workflow

For a reliable packaging process, combine cache clearing with mirror configuration. You can add a convenience script to [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json):

```json
"scripts": {
  "clean-build": "rd /s /q \"%LOCALAPPDATA%\\electron\" && rd /s /q \"%LOCALAPPDATA%\\electron-builder\" && npm run build-app"
}

```

Execute with:

```bash
npm run clean-build

```

This ensures that every build attempt starts with a clean cache and fetches binaries from the configured mirror, eliminating the Electron builder timeout issues described in the source analysis.

## Summary

- **Set `ELECTRON_MIRROR`** to a regional CDN like Tsinghua or npmmirror to bypass slow GitHub downloads.
- **Clear `%LOCALAPPDATA%\electron`** and `%LOCALAPPDATA%\electron-builder` on Windows (or `~/.cache` equivalents on Unix) to remove corrupted partial downloads.
- **Use a standard terminal** instead of VS Code's integrated terminal to ensure proper permissions and environment handling.
- **Remove `"rpm"`** from the Linux targets in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json) if building on Debian/Ubuntu to reduce network overhead.
- **Run `npm run build-app`** (defined in [`package.json`](https://github.com/ai-ql/chat-mcp/blob/main/package.json) lines 14-15) after applying these fixes to package the application successfully.

## Frequently Asked Questions

### What causes Electron Builder to timeout during packaging?

Electron Builder downloads large platform-specific binaries from GitHub's release servers during the packaging process. When these servers are slow, blocked by regional firewalls, or when the network connection is unstable, the download exceeds the default timeout threshold, causing the build to fail.

### Where does Electron Builder store its cache?

On Windows, Electron Builder caches downloaded binaries in `%LOCALAPPDATA%\electron` and `%LOCALAPPDATA%\electron-builder`. On macOS and Linux, the cache is located in `~/.cache/electron` and `~/.cache/electron-builder`. Corrupted files in these directories trigger repeated timeout errors until manually cleared.

### Can I use any CDN mirror for the ELECTRON_MIRROR variable?

Yes, any mirror that hosts the official Electron release binaries in the same directory structure will work. Popular options include `https://mirrors.tuna.tsinghua.edu.cn/electron/` for users in China and `https://npmmirror.com/mirrors/electron/` for global access. The mirror must support the same version paths as the official GitHub releases.

### Why should I avoid VS Code's integrated terminal when building?

VS Code's integrated terminal sometimes runs with restricted permissions or isolated environment contexts that prevent proper cache directory access or environment variable propagation. Using the standard system terminal (Command Prompt, PowerShell, or Terminal) ensures that the `ELECTRON_MIRROR` variable is recognized and that cache clearing operations succeed.