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.

```bash
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`:

```bash
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:

```bash
sudo bash setup-openclaw.sh
```

**Missing packages**:

```bash
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:

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

Check OpenClaw landed:

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

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
# 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.