pipeline_core/skills_library/all/hermes-web-ui-build-troubleshooting/SKILL.md

name	description	trigger_conditions
Hermes Web UI Build Troubleshooting	Diagnose and fix common Web UI build failures in Hermes Agent updates	"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:

   node --version
   

2. Verify Web UI requirements:

   cat package.json | grep -A 3 "engines"
   # Should show: "node": ">=20.0.0"
   

3. Test build directly:

   cd /path/to/hermes/web
   npm run build
   

Solutions

Option 1: Upgrade Node.js (Recommended)

For Ubuntu/Debian systems:

# 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:

  sudo apt remove libnode-dev nodejs-doc -y
  sudo apt install nodejs -y
  

Alternative using snap:

sudo snap install node --channel=20/stable --classic

Option 2: Use Docker (If available)

Hermes Dockerfile includes correct Node.js version:

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:

# 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):

  sudo apt install python3-fastapi python3-uvicorn python3-dotenv -y
  

Create User Service File

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

# 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

# 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