OpenClaw 2026.3.22 npm Install Can Break the Control UI: Missing dist/control-ui and scripts/ui.js

OpenClaw users reported that upgrading a global npm install to OpenClaw 2026.3.22 can leave the gateway reachable while the Control UI becomes unusable.

The key detail: this appears to be a packaging regression in the published npm artifact. The package advertises UI rebuild scripts, but the installed files needed to run them are missing.

Sources:

Issue: openclaw/openclaw#53019
Related report + workaround: openclaw/openclaw#53013

What you’ll see

Typical symptoms after updating to 2026.3.22 (global npm install):

Opening the local dashboard returns an error like:
- “Control UI assets not found. Build them with pnpm ui:build …”
Visiting the gateway root may return 503 (while the gateway process itself is still running).

Why the suggested rebuild command fails (in the npm package)

The reports indicate the published npm tarball for [email protected] is missing:

dist/control-ui/ (built UI assets)
scripts/ui.js (the script referenced by pnpm ui:build, pnpm ui:dev, etc.)

So even though the error message suggests pnpm ui:build, a global npm install may not contain the files required to rebuild the UI in place.

Confirm you’re hitting this specific regression

Confirm version:

openclaw --version

Find where your global package lives:

which openclaw
npm config get prefix

Inspect the installed package contents (path varies by platform; examples from the reports):

# Example: Homebrew prefix on macOS
cd /opt/homebrew/lib/node_modules/openclaw

# Example: Linuxbrew prefix on Linux
cd /home/linuxbrew/.linuxbrew/lib/node_modules/openclaw

ls -la dist/control-ui scripts/ui.js

If dist/control-ui and scripts/ui.js are missing, you’re likely encountering the same packaging issue.

Fast triage: published npm packaging regression vs local build or permission damage

When people first hit missing Control UI assets, they often start by blaming Node, pnpm, permissions, or a dirty local environment. A more useful split is:

The gateway still runs, but both the UI asset directory and scripts/ui.js are missing
- that points much more strongly to a broken published package than to a local build suddenly failing.
Only one machine is broken while other installs of the same version are fine
- then it is worth checking local install paths, permissions, caches, or manually deleted files.
The error message recommends pnpm ui:build, but the installed package does not even contain the script entrypoint
- that means the recovery path itself is invalid for this install shape, not just that the operator skipped a rebuild.
The failure is broader than the UI and the gateway/CLI also behave incorrectly
- then do not keep the scope narrowly limited to missing Control UI assets. Expand the check to wider install corruption or version compatibility issues.

This distinction saves teams from wasting time on the wrong fix path, such as repeatedly reinstalling pnpm or changing permissions when the real failure is in the published artifact contents.

Practical workarounds (until a fixed release)

Option A) Roll back to a known-good version (fastest)

One reporter restored the dashboard by reinstalling an earlier release:

npm uninstall -g openclaw
npm install -g [email protected]
openclaw gateway restart

If you need a different pinned version, choose one that predates 2026.3.22 and is known to include Control UI assets.

Option B) Avoid the global npm artifact for now (source / alternative install)

If your workflow allows it, consider using an installation method that builds the UI from source during install/build, rather than relying on the prepacked global npm artifact. (The failure mode above is specific to the published package contents.)

Option C) Treat the gateway as running, but avoid UI-dependent operations

If the gateway is up and serving API/chat traffic, you may be able to continue using non-UI flows temporarily. But for operational safety, avoid changes that require the dashboard until you’ve rolled back or upgraded to a fixed build.

What maintainers likely need to fix

Based on the issue reports, the npm release should either:

ship dist/control-ui/ in the package, or
ship the scripts and inputs required for pnpm ui:build to work from the installed artifact, or
adjust error messaging so it doesn’t recommend an impossible recovery path for packaged installs.

Common rollout questions

When should you stop debugging your local machine and treat this as a release packaging regression

If the gateway still starts, openclaw --version shows 2026.3.22, and the installed global package is missing both dist/control-ui/ and scripts/ui.js, that is the point to stop treating it like a random local corruption problem. Those signals together strongly indicate a broken published artifact, not a machine-specific UI build mistake.

What should teams pin or verify before rolling out another npm-based OpenClaw upgrade

At minimum, pin the OpenClaw version in deployment scripts and add a post-upgrade check that confirms the installed package still contains the UI asset directory and the rebuild script entrypoint. That turns this incident from a surprise outage into a fast pass/fail check before operators discover a dead dashboard.

What is the fastest on-call check before a team wastes time rebuilding the UI locally?

Check whether the installed global package already contains both dist/control-ui/ and scripts/ui.js.

If both are missing, treat the incident first as a published package contents problem, not as a local rebuild mistake.
If both files exist, then it becomes more reasonable to inspect local permissions, incomplete upgrades, or a damaged install path.

That single split usually saves more time than jumping straight into repeated pnpm ui:build attempts.