How to Fix Electron Builder Timeout Issues During Packaging

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 (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):

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

On Windows (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 (lines 186-188), remove these directories on Windows:

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 (lines 38-43) to exclude the RPM format:

"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:

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

Execute with:

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 if building on Debian/Ubuntu to reduce network overhead.
• Run npm run build-app (defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}