openboatmobile-ai/docs/TROUBLESHOOTING.md

# Troubleshooting

Common issues and their solutions.

## Deployment Issues

### Terraform Error: "Provider produced inconsistent result"

**Cause:** State file conflicts or provider version mismatch.

**Solution:**
```bash
terraform init -upgrade
terraform plan -refresh=false
```

### Terraform Error: "API Token invalid"

**Hetzner:**
- Token must have Read & Write permissions
- Copy immediately after creation (shown only once)
- Check for trailing spaces in `.env`

**DigitalOcean:**
- Regenerate token in DO Console
- Verify token has Read & Write scope

### Terraform Error: "SSH Key not found"

**Hetzner:**
- Key name must match exactly as shown in Console
- Case-sensitive
- Use the name: `TF_VAR_ssh_key_names='["my-key-name"]'`

**DigitalOcean:**
- Use the fingerprint, not the name
- Get fingerprint: `ssh-keygen -lf ~/.ssh/id_ed25519.pub`
- Format: `TF_VAR_ssh_key_fingerprints='["abc123..."]'`

### Terraform State Locked

**Cause:** Previous `terraform apply` crashed or is still running.

**Solution:**
```bash
# Force unlock (if sure no other apply is running)
terraform force-unlock <LOCK_ID>
```

## Connection Issues

### SSH Connection Refused

**Causes:**
1. Cloud-init still running
2. Firewall blocking your IP
3. Wrong SSH key

**Solutions:**

1. Wait2-3 minutes after deployment, then retry
2. Check cloud-init status:
   ```bash
   # On the server
   cloud-init status
   tail -f /var/log/cloud-init-output.log
   ```
3. Restrict firewall to your IP:
   ```bash
   TF_VAR_ssh_allowed_ips='["your.public.ip/32"]'
   ```
4. Verify SSH key:
   ```bash
   ssh-add -l  # Should show your key
   ssh -v openclaw@<ip>  # Verbose output
   ```

### SSH Permission Denied

**Causes:**
1. Wrong username
2. Wrong SSH key
3. Key not added to agent

**Solutions:**

1. Username is `openclaw` (not `root`):
   ```bash
   ssh <username>@<ip>  # username is 'openclaw' or 'hermes' depending on framework
   ```

2. Verify key is correct:
   ```bash
   ssh -i ~/.ssh/id_ed25519 openclaw@<ip>
   ```

3. Add key to agent:
   ```bash
   ssh-add ~/.ssh/id_ed25519
   ```

### Connection Times Out

**Causes:**
1. Wrong IP
2. Server not running
3. Network issues

**Solutions:**

1. Verify IP from Terraform output:
   ```bash
   terraform output server_ip
   ```

2. Check server status in cloud console

3. Try from different network (e.g., mobile hotspot)

## Cloud-Init Issues

### Cloud-init Stuck

**Check status:**
```bash
cloud-init status --wait
```

**Check logs:**
```bash
tail -f /var/log/cloud-init-output.log
```

**Common issues:**
- Network timeout downloading packages
- Package repository issues
- Disk space exhaustion

### OpenClaw Command Not Found

**Cause:** Cloud-init hasn't finished or failed.

**Solution:**
```bash
# Check if Node.js is installed
node --version

# Check if Node.js setup ran
ls /etc/apt/sources.list.d/nodesource.list

# Manually install if needed
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
sudo apt-get install -y nodejs
```

### Disk Full

**Cause:** Small instance with lots of logs.

**Solution:**
```bash
# Check disk usage
df -h

# Clean package cache
sudo apt-get clean

# Remove old logs
sudo journalctl --vacuum-size=100M
```

## Tailscale Issues

### Tailscale Not Connected

**Check status:**
```bash
sudo tailscale status
```

**Reconnect:**
```bash
sudo tailscale up --authkey=tskey-auth-xxxxx
```

### "Serve platform not enabled"

**Solution:**
1. Go to [Tailscale Admin → Serve](https://login.tailscale.com/admin/settings/serve)
2. Enable the Serve feature

### Gateway Not Accessible on Tailnet

**Check gateway:**
```bash
sudo lsof -i :18789
sudo systemctl status openclaw-gateway
```

**Check serve:**
```bash
sudo tailscale serve status
```

**Verify firewall:**
```bash
sudo ufw status
# Should show 18789 allowed on tailscale0
```

## Discord Issues

### Bot Doesn't Respond

**Check:**
1. Bot token is correct
2. Message Content Intent is enabled
3. Bot is in your server
4. Server ID and User ID are correct

**Debug:**
```bash
# Check gateway logs
journalctl -u openclaw-gateway -f | grep -i discord
```

### "Unauthorized" in Logs

**Cause:** Your user ID is not in the allowlist.

**Solution:**
Edit `~/.openclaw/openclaw.json` and add your Discord user ID:
```json
{
  "channels": {
    "discord": {
      "guilds": {
        "SERVER_ID": {
          "users": ["YOUR_USER_ID"]
        }
      }
    }
  }
}
```

### Gateway Shows Pairing Code

**Solution:**
```bash
# On the server
openclaw pairing approve device <CODE>
```

## Performance Issues

### Gateway Slow to Respond

**Causes:**
1. High model load
2. Network latency
3. Instance too small

**Solutions:**
1. Check model usage:
   ```bash
   top
   htop
   ```

2. Check network:
   ```bash
   ping api.venice.ai
   ```

3. Upgrade instance:
   ```bash
   # Edit terraform.tfvars
   server_type_hetzner = "cpx21"  # More CPU/RAM
   terraform apply
   ```

### Memory Exhaustion

**Check:**
```bash
free -h
```

**Solution:**
```bash
# Add swap (if not present)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```

## Getting Help

1. Check OpenClaw docs: [docs.openclaw.ai](https://docs.openclaw.ai)
2. Search GitHub issues: [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
3. Community Discord: [discord.com/invite/clawd](https://discord.com/invite/clawd)