u-claw/bootable/TROUBLESHOOTING.md

Troubleshooting the bootable USB

While building the drive

Ventoy will not install

"Access Denied", or it cannot write to the drive.

1. Run PowerShell as Administrator
2. Close anything holding the drive open — File Explorer, antivirus, backup tools
3. Try Ventoy's read-only install mode
4. Check for a physical write-protect switch on the drive

The ISO download is slow or fails

The script pulls from releases.ubuntu.com and verifies the SHA256. If it keeps failing, download it yourself:

• https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso

Put it in bootable/.download-cache/ and run 2-download-iso.ps1 again — it finds the cached file and verifies it rather than downloading again.

Not enough space for the persistence image

3-create-persistence.ps1 needs room for a 20 GB file alongside a 5.8 GB ISO.

• A 32 GB drive is the practical minimum
• Change $PersistenceSizeGB in the script to use less
• Below about 8 GB there is not enough room to install anything meaningful

While booting

Black screen, or it hangs before the desktop

Press F6 or Esc at the boot menu to add kernel parameters:

Parameter	What it does
nomodeset	Skips the graphics driver — the usual fix
nouveau.modeset=0	For NVIDIA cards specifically
quiet splash	Removes the splash screen so you can see where it stops

It drops into an initramfs prompt

persistence.dat has no ext4 filesystem in it. This is the single most common build failure, and the error message says nothing about the real cause.

sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat

Then reboot — formatting does not take effect in the same session.

To check whether a file is actually formatted, read two bytes at offset 1080; they should be 0x53 0xEF.

No USB entry in the boot menu

• Try a different port
• In BIOS: disable Secure Boot, enable USB boot
• Try both UEFI and Legacy/CSM modes

After booting

The OpenClaw install fails

Network — it needs to reach nodejs.org and registry.npmjs.org:

curl -I https://registry.npmjs.org
curl -I https://nodejs.org/dist

# behind a corporate proxy
export http_proxy=http://your-proxy:port
export https_proxy=http://your-proxy:port

Permissions — it has to run as root:

sudo bash setup-openclaw.sh

Missing packages:

sudo apt-get update && sudo apt-get install curl xdg-utils

U-Claw will not start

Check Node.js is there and is the version we pin:

/opt/u-claw/runtime/node-linux-x64/bin/node --version

Check OpenClaw landed:

ls -la /opt/u-claw/core/node_modules/openclaw/

Check for a port conflict — U-Claw uses 18789 to 18799:

ss -tlnp | grep :18789

# start it somewhere else if something else owns the range
cd /opt/u-claw/core
node node_modules/openclaw/openclaw.mjs gateway run --port 18800

The browser does not open by itself

Go to http://localhost:18789 yourself. Ubuntu Live normally has no firewall, but if you suspect one:

sudo ufw status

Data disappears after a reboot

1. Make sure you picked the persistence entry in the Ventoy menu
2. Check the file is the size you expect:

ls -lh /media/*/Ventoy/persistence.dat

3. If it is corrupt, re-run 3-create-persistence.ps1 on the Windows machine

Everything is slow

Some of this is unavoidable — a USB drive is slower than a disk. What helps:

• USB 3.0 drive in a USB 3.0 port. The largest single difference by far.
• Turn down desktop effects: sudo apt-get install gnome-tweaks
• Add swap, if you are running with persistence:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Inference happens at your model provider, so conversation speed is not affected by any of this — only startup and file operations are.

Wi-Fi, Bluetooth or sound does not work

With persistence enabled you can install drivers and keep them:

sudo apt-get update
sudo apt-get install linux-generic-hwe-24.04    # newer kernel

ubuntu-drivers devices                          # what is available
sudo ubuntu-drivers autoinstall                 # install the recommended ones

If Wi-Fi still will not come up, tether over USB from a phone — it needs no drivers.

Digging deeper

# U-Claw's own log
tail -f /opt/u-claw/data/logs/openclaw.log

# kernel and system
dmesg | tail -20
journalctl -xe

# is the network reachable
curl -I https://registry.npmjs.org

# where the space went
df -h /media/*/Ventoy
du -sh /opt/u-claw/*

If it will not boot at all

1. Get your data off first. Plug the drive into any Windows or Mac machine — the Ventoy data partition is readable, so back up anything under u-claw-linux/ before you touch anything else.
2. Rebuild. Format the drive and run the four PowerShell scripts again.
3. Ask. Open an issue at https://gitea.fanghe.it.com/zhenghy/u-claw/issues with what you saw on screen and which step it failed at.

Getting a better result

When building: use a good USB 3.0 drive, give persistence at least 20 GB, and turn off real-time antivirus scanning for the build — it slows the ISO write enormously and occasionally corrupts it.

On first boot: run the system updates and install the recommended drivers once, while you have network. With persistence on, you only do it once.

Long term: if you find yourself using it daily on the same machine, a real dual-boot install will be faster than any USB drive can be.