---
name: "Hermes Web UI Build Troubleshooting"
description: "Diagnose and fix common Web UI build failures in Hermes Agent updates"
trigger_conditions:
  - "\"hermes update\" shows \"Web UI build failed\""
  - "npm run build fails with SyntaxError about unexpected tokens"
  - "TypeScript compilation errors in Hermes web directory"
---

# Hermes Web UI Build Troubleshooting Guide

## Problem Identification

### Common Error Patterns
- **SyntaxError with `??` operator**: Indicates Node.js version too old (< v14)
- **TypeScript compilation errors**: Often related to Node.js engine compatibility
- **Dependency conflicts**: Package version mismatches during npm install
- **Missing Python dependencies**: FastAPI, uvicorn, python-dotenv not installed

### Version Requirements
- **Hermes Web UI requires Node.js >= 20.0.0**
- **System Node.js is often v12-v16 on older systems**
- Check with: `node --version`

## Common Issue: Node.js Version Incompatibility

The most frequent cause of Web UI build failure is **Node.js version mismatch**.

### Symptoms
- `hermes update` shows "⚠ Web UI build failed (hermes web will not be available)"
- Running `npm run build` in `/web` directory produces:
  ```
  SyntaxError: Unexpected token '?'
  ```
- Error occurs in TypeScript compiler (`tsc`) or Vite build tools

### Root Cause
- Hermes Web UI requires **Node.js >= 20.0.0**
- System has older Node.js version (commonly v12.x or v14.x)
- Modern JavaScript syntax (nullish coalescing `??`, optional chaining `?.`) not supported

### Diagnosis Steps

1. **Check current Node.js version**:
   ```bash
   node --version
   ```

2. **Verify Web UI requirements**:
   ```bash
   cat package.json | grep -A 3 "engines"
   # Should show: "node": ">=20.0.0"
   ```

3. **Test build directly**:
   ```bash
   cd /path/to/hermes/web
   npm run build
   ```

### Solutions

#### Option 1: Upgrade Node.js (Recommended)
For Ubuntu/Debian systems:
```bash
# Add NodeSource repository for Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Handle common package conflicts that prevent installation
sudo apt remove libnode-dev nodejs-doc -y

# Install Node.js 20
sudo apt install nodejs -y

# Verify upgrade
node --version  # Should show v20.x.x
npm --version   # Should show 10.x.x
```

### Handling Package Conflicts During Upgrade
If `sudo apt install nodejs` fails with dpkg errors about file conflicts:
- **Common error**: "trying to overwrite '/usr/include/node/common.gypi', which is also in package libnode-dev"
- **Solution**: Remove conflicting packages first:
  ```bash
  sudo apt remove libnode-dev nodejs-doc -y
  sudo apt install nodejs -y
  ```

Alternative using snap:
```bash
sudo snap install node --channel=20/stable --classic
```

#### Option 2: Use Docker (If available)
Hermes Dockerfile includes correct Node.js version:
```bash
docker build -t hermes-agent .
```

#### Option 3: Skip Web UI (Temporary)
- Web UI build is **optional** - core CLI functionality works without it
- Continue using Hermes Agent normally via command line
- Fix Web UI later when Node.js can be upgraded

### Important Notes
- Hermes Agent core functionality (CLI) is **unaffected** by Web UI build failure
- The update successfully applied 793 commits to core code
- Web Dashboard is an optional feature, not required for basic operation
- Downgrading dependencies is **not recommended** due to peer dependency conflicts

### Verification
After fixing Node.js version:
```bash
# Navigate to web directory
cd /path/to/hermes/web

# Restore original package.json if it was modified during troubleshooting
git checkout package.json

# Install dependencies (use --legacy-peer-deps if peer dependency conflicts occur)
npm install

# Build Web UI
npm run build
# Should complete successfully with output showing transformed modules and built files

# Verify build artifacts exist
ls -la ../hermes_cli/web_dist/
# Should contain index.html, assets/, fonts/, etc.

hermes dashboard  # Should start without build errors
```

## Automatic Startup with Systemd

To automatically start Hermes Dashboard on system boot/user login:

### Prerequisites
- Ensure Python dependencies are installed system-wide (not just in virtual environment):
  ```bash
  sudo apt install python3-fastapi python3-uvicorn python3-dotenv -y
  ```

### Create User Service File
```bash
mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/hermes-dashboard.service << 'EOF'
[Unit]
Description=Hermes Agent Web Dashboard
After=network.target
Wants=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/hermes-agent
Environment=PATH=/usr/bin:/usr/local/bin
ExecStart=/usr/bin/python3 -m hermes_cli.main dashboard --port 9119 --no-open
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hermes-dashboard

[Install]
WantedBy=default.target
EOF
```

### Enable and Start Service
```bash
# Reload systemd configuration
systemctl --user daemon-reload

# Enable auto-start on login
systemctl --user enable hermes-dashboard.service

# Start immediately
systemctl --user start hermes-dashboard.service
```

### Verify Service Status
```bash
# Check if running
systemctl --user status hermes-dashboard.service

# View logs
journalctl --user -u hermes-dashboard.service -f

# Check port binding
ss -tlnp | grep 9119
```

### Troubleshooting Service Issues
- **Service fails to start**: Check that all Python dependencies are available system-wide
- **Permission errors**: Ensure the user has read access to the Hermes installation directory
- **Port conflicts**: Default port is 9119; change with `--port` parameter if needed
- **Virtual environment issues**: If using venv, update `ExecStart` to use the full venv Python path

### Access Dashboard
Once service is running, access at: `http://localhost:9119`