Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Bug]: Control UI completely blank on main branch: "process is not defined" & "path.resolve is not a function" due to Node.js modules in frontend [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#62311•Fetched 2026-04-08 03:06:14
View on GitHub
Comments
1
Participants
2
Timeline
4
Reactions
0
Author
benniechenbinbenniechenbin
Participants
benniechenbinbenniechenbindeepgemdeepgem
Timeline (top)
labeled ×2commented ×1subscribed ×1

Error Message

Uncaught ReferenceError: process is not defined at hv (home-dir.ts:71:64) at yv (utils.ts:144:28)

Root Cause

There is a severe backend-to-frontend dependency leak. Pure Node.js backend utility files (specifically src/infra/home-dir.ts and src/utils.ts which rely on process.env, os.homedir, and path.resolve) are being imported into the Control UI component tree.

Since Vite externalizes these Node built-ins for the browser, they become undefined or empty objects at runtime. When the browser tries to access process.env or execute path.resolve(), the JavaScript thread crashes.

Fix Action

Fix / Workaround

After attempting to hotfix the process issue locally, it immediately hits the next externalized module error:

Code Example

[plugin rolldown:vite-resolve] Module "node:os" has been externalized for browser compatibility, imported by ".../src/infra/home-dir.ts".
[plugin rolldown:vite-resolve] Module "node:path" has been externalized for browser compatibility, imported by ".../src/infra/home-dir.ts".

---

Uncaught ReferenceError: process is not defined
    at hv (home-dir.ts:71:64)
    at yv (utils.ts:144:28)

---

Uncaught TypeError: lv.default.resolve is not a function
    at hv (home-dir.ts:77:56)
    at yv (utils.ts:144:28)

---
RAW_BUFFERClick to expand / collapse

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

Bug Description

On the latest main branch, building and accessing the Control UI (Dashboard) results in a completely blank screen.

The Vite build process throws multiple warnings about externalizing Node.js built-in modules (node:fs, node:os, node:path), and the browser console throws fatal runtime errors because Node.js specific globals (like process and path) are leaking into the frontend build.

Steps to Reproduce

  1. Checkout the latest main branch.
  2. Run pnpm install
  3. Run pnpm build and pnpm ui:build
  4. Start the gateway: openclaw gateway restart
  5. Open the Control UI in the browser.

Expected Behavior

The Control UI should render properly without runtime crashes.

Actual Behavior

The web interface is a completely blank white screen.

During pnpm ui:build, Vite throws these warnings:

[plugin rolldown:vite-resolve] Module "node:os" has been externalized for browser compatibility, imported by ".../src/infra/home-dir.ts".
[plugin rolldown:vite-resolve] Module "node:path" has been externalized for browser compatibility, imported by ".../src/infra/home-dir.ts".

In the browser DevTools Console (F12), the following fatal errors halt the rendering engine:

Uncaught ReferenceError: process is not defined
    at hv (home-dir.ts:71:64)
    at yv (utils.ts:144:28)

After attempting to hotfix the process issue locally, it immediately hits the next externalized module error:

Uncaught TypeError: lv.default.resolve is not a function
    at hv (home-dir.ts:77:56)
    at yv (utils.ts:144:28)

Root Cause Analysis

There is a severe backend-to-frontend dependency leak. Pure Node.js backend utility files (specifically src/infra/home-dir.ts and src/utils.ts which rely on process.env, os.homedir, and path.resolve) are being imported into the Control UI component tree.

Since Vite externalizes these Node built-ins for the browser, they become undefined or empty objects at runtime. When the browser tries to access process.env or execute path.resolve(), the JavaScript thread crashes.

Suggested Fix

Backend-specific utilities (like home-dir.ts) must be strictly decoupled from the frontend UI components. Any shared utilities imported by the frontend must be isomorphic (browser-safe) and avoid direct calls to Node.js globals like process, fs, path, or os.

Environment

  • OS: Linux / WSL (Ubuntu)

  • Node.js: v22.22.2

  • Branch: main (latest commits)

  • Install method: source compilation (pnpm ui:build)

Steps to reproduce

  1. pnpm install
  2. pnpm ui:build
  3. pnpm build

Expected behavior

The Control UI should load and render properly in the browser without any blank screens or runtime crashes after running pnpm ui:build.

Actual behavior

The web interface displays a completely blank white screen. When opening the browser's DevTools Console (F12), fatal runtime errors are thrown because Node.js specific globals are leaking into the frontend build:

Uncaught ReferenceError: process is not defined at hv (home-dir.ts:71)

Uncaught TypeError: ...resolve is not a function at hv (home-dir.ts:77)

OpenClaw version

2026.4.5

Operating system

windows10 wsl2

Install method

source compilation (pnpm ui:build)

Model

qwen2.5

Provider / routing chain

ollama

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

No response

Additional information

No response

extent analysis

TL;DR

Decoupling backend-specific utilities from the frontend UI components and ensuring shared utilities are isomorphic should resolve the dependency leak issue.

Guidance

  • Identify and refactor backend-specific utility files (like home-dir.ts and utils.ts) to avoid direct imports in the frontend UI component tree.
  • Create browser-safe, isomorphic versions of shared utilities that do not rely on Node.js globals like process, fs, path, or os.
  • Verify the fix by checking for the absence of Uncaught ReferenceError and Uncaught TypeError in the browser console after rebuilding and restarting the application.
  • Consider using a linter or code analyzer to detect and prevent similar backend-to-frontend dependency leaks in the future.

Example

// Before (backend-specific utility)
import { homedir } from 'os';
import { resolve } from 'path';

// After (isomorphic utility)
import { homedir } from 'os-browserify'; // or a similar browser-safe alternative
import { resolve } from 'path-browserify'; // or a similar browser-safe alternative

Notes

The provided home-dir.ts and utils.ts files seem to be the primary sources of the issue, but a thorough code review may be necessary to identify all affected areas.

Recommendation

Apply a workaround by creating isomorphic versions of the affected utilities and refactoring the frontend code to use these new utilities, as this approach directly addresses the identified root cause of the problem.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

The Control UI should load and render properly in the browser without any blank screens or runtime crashes after running pnpm ui:build.

#model save/load#optimization#mixed precision#training loop#runtime error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING