openclaw - 💡(How to fix) Fix [Bug]: v2026.4.29 gateway fails on native Windows — bundled plugin runtime deps EPERM (MAX_PATH + npm/pnpm rename) [1 comments, 2 participants]

Bug type

Crash (process/app exits or hangs)

Summary

After upgrading from v2026.4.27 to v2026.4.29 on native Windows 11 (Node 24.13.1, npm 11.8.0), the gateway fails to start with Gateway failed to start: Error: Startup failed: required secrets are unavailable. The real error is EPERM: operation not permitted, rename during bundled plugin runtime dependency installation — both npm and pnpm fail with EPERM on Windows-specific rename operations.

Two independent root causes compound into the failure:

Root Cause #1 — npm tar extraction EPERM

npm's internal tar module gets EPERM when renaming .DELETE.* files during node_modules extraction. Windows rename() does not overwrite existing files (unlike Unix), so when npm tries rename('index.js' -> 'index.js.DELETE.<hash>') and the target already exists from a previous attempt, it fails.

Affected paths: node_modules/degenerator/dist/index.js, socks-proxy-agent/dist/index.js, node-downloader-helper/bin/ndh, etc. — all https-proxy-agent/dist/index.js instances across nested deps.

Root Cause #2 — pnpm store MAX_PATH overflow (primary)

pnpm's store-dir is created at:

C:\Users\<user>\.openclaw\plugin-runtime-deps\openclaw-2026.4.29-<hash>\.openclaw-pnpm-store\v10\files\<bucket>\<sha512-hash>

The SHA-512 content-addressed filename is 128 hex chars. Combined with the deep mirror path, the total path is ~277 characters — exceeding Windows MAX_PATH=260. The pnpm rename of temp tarball files (<hash>204041 → <hash>) fails with ERR_PNPM_EPERM.

Specific failure: libsignal-node tarball from GitHub (@whiskeysockets/[email protected] dependency) consistently fails.

Environment

Steps to reproduce

1. npm i -g [email protected] on native Windows
2. openclaw gateway start (or launch via gateway.cmd)
3. Gateway starts staging bundled plugin runtime deps (938 packages)
4. npm install in mirror directory fails with EPERM on node-downloader-helper/bin/ndh
5. OR pnpm install fails with ERR_PNPM_EPERM on libsignal-node tarball store rename

Observed behavior

With npm (initial code path):

npm warn tar TAR_ENTRY_ERROR EPERM: operation not permitted, rename '<path>/node_modules/degenerator/dist/index.js' -> '<path>/node_modules/degenerator/dist/index.js.DELETE.<hash>'
npm error code EPERM
npm error syscall rename
npm error path <path>/node_modules/node-downloader-helper/bin/ndh.1725784861
npm error The operation was rejected by your operating system.
Gateway failed to start: Error: Startup failed: required secrets are unavailable.

With pnpm (after installing pnpm globally):

 WARN  GET https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/<hash> error (ERR_PNPM_EPERM). Will retry in 10 seconds.
 ERR_PNPM_EPERM  Failed to add tarball ... to store: EPERM: operation not permitted, rename '<hash>204041' -> '<hash>'

Workaround

Two-step workaround that successfully starts the gateway:

1. Pre-install deps manually with npm (warnings are non-fatal):

   npm install --production --ignore-scripts --no-audit --no-fund --legacy-peer-deps

   (920 packages installed in ~2 minutes, EPERM warnings are non-fatal and can be ignored)

2. Start the gateway — it detects node_modules already exists and skips the install step.

Short-term code fix suggestions

Fix #1 — Shorten pnpm store-dir path (addresses Root Cause #2)

In bundled-runtime-deps-*.js, line ~642:

// Before:
pnpmArgs: createBundledRuntimeDepsPnpmInstallArgs({ storeDir: path.join(params.installExecutionRoot, ".openclaw-pnpm-store") })
// After:
pnpmArgs: createBundledRuntimeDepsPnpmInstallArgs({ storeDir: path.join(os.homedir(), ".openclaw", "pnpm-store") })

This shortens the path from ~277 chars to ~207, preventing MAX_PATH overflow.

Fix #2 — EPERM fallback for renameSync (addresses Root Cause #1)

Existing pattern in json-file-Cq418mQ6.js:56-68 (renameJsonFileWithFallback: catch EPERM/EEXIST → copyFileSync) — same pattern needed in:

• bundled-runtime-root-*.js: materializeBundledRuntimeMirrorFile, replaceBundledRuntimeMirrorSymlinkAtomic, copyBundledRuntimeMirrorFileAtomic
• bundled-runtime-deps-*.js: replaceNodeModulesDir
• shared-*.js: writeTextFileAtomic

Fix #3 — pnpm.cmd detection on Windows

resolveBundledRuntimeDepsPnpmRunner searches for pnpm.exe but not pnpm.cmd:

const names = platform === "win32" ? ["pnpm.exe", "pnpm.cmd"] : ["pnpm"];

Impact and severity

High — Gateway completely fails to start on native Windows. 20+ stability failure files generated across multiple attempts. pnpm store path issue affects every user with username longer than ~8 characters.