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:

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:

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

   # On the server
   cloud-init status
   tail -f /var/log/cloud-init-output.log
   

3. Restrict firewall to your IP:

   TF_VAR_ssh_allowed_ips='["your.public.ip/32"]'
   

4. Verify SSH key:

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

   ssh <username>@<ip>  # username is 'openclaw' or 'hermes' depending on framework
   

2. Verify key is correct:

   ssh -i ~/.ssh/id_ed25519 openclaw@<ip>
   

3. Add key to agent:

   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:

   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:

cloud-init status --wait

Check logs:

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:

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

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

sudo tailscale status

Reconnect:

sudo tailscale up --authkey=tskey-auth-xxxxx

"Serve platform not enabled"

Solution:

1. Go to Tailscale Admin → Serve
2. Enable the Serve feature

Gateway Not Accessible on Tailnet

Check gateway:

sudo lsof -i :18789
sudo systemctl status openclaw-gateway

Check serve:

sudo tailscale serve status

Verify firewall:

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:

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

{
  "channels": {
    "discord": {
      "guilds": {
        "SERVER_ID": {
          "users": ["YOUR_USER_ID"]
        }
      }
    }
  }
}

Gateway Shows Pairing Code

Solution:

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

   top
   htop
   

2. Check network:

   ping api.venice.ai
   

3. Upgrade instance:

   # Edit terraform.tfvars
   server_type_hetzner = "cpx21"  # More CPU/RAM
   terraform apply
   

Memory Exhaustion

Check:

free -h

Solution:

# 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
2. Search GitHub issues: github.com/openclaw/openclaw
3. Community Discord: discord.com/invite/clawd