remoteturtle/TROUBLESHOOTING.md

# 🔧 Troubleshooting Guide

## Installation Issues

### Node.js Not Found

**Problem:** `command not found: node` or `'node' is not recognized`

**Solution:**
1. Install Node.js from https://nodejs.org/ (LTS version recommended)
2. Restart your terminal after installation
3. Verify: `node --version` should show v18.0.0 or higher

### npm Install Fails

**Problem:** Errors during `npm install`

**Solutions:**
- Clear npm cache: `npm cache clean --force`
- Delete `node_modules` folders and try again
- Update npm: `npm install -g npm@latest`
- Check your internet connection
- Try: `npm install --legacy-peer-deps`

## Server Issues

### Port Already in Use

**Problem:** `Error: listen EADDRINUSE: address already in use :::3001`

**Solution 1 - Change Ports:**
1. Edit `server/server.js`:
   ```javascript
   const PORT = 3005;  // Change from 3001
   const WS_PORT = 3006;  // Change from 3002
   ```

2. Edit `client/src/store/turtleStore.js`:
   ```javascript
   const WS_URL = 'ws://localhost:3006';
   const API_URL = 'http://localhost:3005';
   ```

**Solution 2 - Kill Existing Process:**

Linux/Mac:
```bash
lsof -ti:3001 | xargs kill -9
lsof -ti:3002 | xargs kill -9
```

Windows:
```cmd
netstat -ano | findstr :3001
taskkill /PID <PID_NUMBER> /F
```

### Server Won't Start

**Problem:** Server crashes on start

**Checklist:**
- [ ] Dependencies installed? Run `cd server && npm install`
- [ ] Node.js version 18+? Check with `node --version`
- [ ] Firewall blocking ports? Add exception for ports 3001-3002
- [ ] Check server logs for specific error messages

## Client Issues

### White Screen / Nothing Renders

**Problem:** Browser shows blank page

**Solutions:**
1. Open browser console (F12) and check for errors
2. Verify server is running: http://localhost:3001/api/turtles
3. Clear browser cache (Ctrl+Shift+Delete)
4. Try incognito/private mode
5. Try different browser (Chrome/Firefox recommended)

### WebSocket Connection Failed

**Problem:** Red "Disconnected" status in top-right

**Solutions:**
1. Check server console for errors
2. Verify WebSocket port (3002) is open
3. Check browser console for WebSocket errors
4. Ensure server URL is correct in `turtleStore.js`
5. Firewall may be blocking WebSocket - add exception

### 3D Map Not Showing

**Problem:** Map area is black or shows errors

**Solutions:**
- WebGL not supported: Update graphics drivers
- Browser compatibility: Use Chrome 90+ or Firefox 88+
- Hardware acceleration disabled: Enable in browser settings
  - Chrome: Settings → System → Use hardware acceleration
  - Firefox: Settings → Performance → Use hardware acceleration
- GPU issues: Try different browser

## Minecraft/ComputerCraft Issues

### Bridge Computer Not Connecting

**Problem:** `webbridge.lua` runs but no connection to server

**Checklist:**
1. Verify SERVER_URL is correct:
   ```lua
   local SERVER_URL = "http://localhost:3001"
   ```
   - Use computer's IP if server is remote
   - Don't use `https://` (use `http://`)

2. Check HTTP API is enabled:
   - Edit `config/computercraft-server.toml` or `.minecraft/config/computercraft.cfg`
   - Find: `enable_http = true`
   - Ensure your server URL is not in `blocked_domains`

3. Test HTTP manually:
   ```lua
   local response = http.get("http://localhost:3001/api/turtles")
   print(response ~= nil)  -- Should print true
   ```

### Turtles Not Appearing in Web

**Problem:** Bridge runs, but no turtles show up

**Diagnosis:**
1. Check bridge computer console for "Status from Turtle X" messages
2. Check server console for "Status update from Turtle X" messages
3. Check web browser console for WebSocket messages

**Common Causes:**
- Channel mismatch - Verify all scripts use same channels:
  - `turtle.lua`: STATUS_CHANNEL = 102
  - `webbridge.lua`: STATUS_CHANNEL = 102
  
- Modem not equipped on turtle
- Turtles out of wireless range
- Turtles not running `turtle.lua` script

### GPS Not Working

**Problem:** Turtles show "No GPS"

**Solution - Set Up GPS Hosts:**

1. Place 4 computers at high altitude (Y=200+)
2. Arrange in square pattern (20+ blocks apart)
3. Give each a wireless modem
4. Run on each:
   ```lua
   gps host X Y Z
   ```
   Replace X Y Z with that computer's actual coordinates

5. Test from turtle:
   ```lua
   x, y, z = gps.locate(5)
   print(x, y, z)  -- Should print coordinates
   ```

### Modem Not Found

**Problem:** `No wireless modem found!`

**Solutions:**
- Craft wireless modem (Stone + Ender Pearl)
- Equip to turtle: Right-click turtle with modem
- For computer: Place modem adjacent and right-click
- Verify: `peripheral.find("modem")` should not be nil

### Commands Not Reaching Turtles

**Problem:** Click commands in web but turtle doesn't respond

**Debug Steps:**

1. Check server receives command:
   - Server console should show: `Command queued for turtle X`

2. Check bridge polls for commands:
   - Bridge console should show: `Command for Turtle X: <command>`

3. Check turtle receives command:
   - Add debug to `turtle.lua`:
   ```lua
   print("Received message:", textutils.serialize(message))
   ```

4. Verify channels match:
   - Web → Server → Bridge → Modem Channel 100 → Turtle

## Performance Issues

### Laggy 3D Map

**Solutions:**
- Reduce number of visible turtles
- Lower browser zoom level
- Close other browser tabs
- Update graphics drivers
- Try lower graphics settings in browser

### Server Using Too Much Memory

**Solutions:**
- Restart server periodically
- Reduce `statusUpdateInterval` in turtle.lua (less frequent updates)
- Clear old turtle data: restart server

### High Network Usage

**Solutions:**
- Increase `statusUpdateInterval` in turtle.lua (default: 5 seconds)
- Reduce number of active turtles
- Use local server instead of remote

## Browser-Specific Issues

### Chrome

**WebSocket closes immediately:**
- Disable browser extensions (especially ad blockers)
- Clear site data: F12 → Application → Clear storage

### Firefox

**3D map performance poor:**
- Enable WebRender: about:config → gfx.webrender.all → true

### Safari

**Not recommended** - Limited WebGL support. Use Chrome or Firefox.

## Network Issues

### Can't Access from Other Devices

**Problem:** Works on localhost but not from other computers

**Solution:**

1. Get your computer's IP address:
   ```bash
   # Linux/Mac
   ifconfig | grep "inet "
   
   # Windows
   ipconfig
   ```
   Example: 192.168.1.100

2. Update configs to use IP instead of localhost:
   
   **webbridge.lua:**
   ```lua
   local SERVER_URL = "http://192.168.1.100:3001"
   ```
   
   **client/src/store/turtleStore.js:**
   ```javascript
   const WS_URL = 'ws://192.168.1.100:3002';
   const API_URL = 'http://192.168.1.100:3001';
   ```

3. Configure firewall:
   
   **Linux:**
   ```bash
   sudo ufw allow 3000:3002/tcp
   ```
   
   **Windows:**
   - Windows Defender Firewall → Advanced Settings
   - Inbound Rules → New Rule
   - Port: 3000-3002
   - Allow the connection

4. Access from other device: `http://192.168.1.100:3000`

### Minecraft Server and Web Server on Different Machines

**Setup:**
- Computer A: Minecraft + Bridge
- Computer B: Node.js Server + Web Client

**Configuration:**

1. On Computer A (Minecraft), edit `webbridge.lua`:
   ```lua
   local SERVER_URL = "http://<Computer_B_IP>:3001"
   ```

2. On Computer B, server.js needs no changes

3. Access web interface from anywhere: `http://<Computer_B_IP>:3000`

## Common Error Messages

### "Failed to send to server"

**In webbridge.lua console**

**Cause:** Bridge can't reach Node.js server

**Fix:**
- Verify server is running
- Check SERVER_URL is correct
- Test: `http.get(SERVER_URL .. "/api/turtles")`

### "Turtle not found"

**In server logs**

**Cause:** Turtle ID not in server's turtle map

**Fix:**
- Turtle hasn't sent status update yet - wait 5 seconds
- Restart turtle script
- Check turtle is broadcasting on correct channel

### "WebSocket connection failed"

**In browser console**

**Cause:** Can't connect to WebSocket server

**Fix:**
- Verify server is running
- Check port 3002 is open
- Update WS_URL in turtleStore.js
- Disable VPN/proxy

## Still Having Issues?

### Collect Debug Information

1. **Server logs**: Copy output from server terminal
2. **Browser console**: F12 → Console tab → Copy errors
3. **Minecraft logs**: Check bridge computer output
4. **Network test**: Can you access http://localhost:3001/api/turtles?

### Reset Everything

Sometimes easiest to start fresh:

```bash
# Stop all servers (Ctrl+C)

# Clean and reinstall
rm -rf server/node_modules client/node_modules
cd server && npm install
cd ../client && npm install

# Restart
./start.sh  # or start.bat on Windows
```

### Check Versions

```bash
node --version    # Should be v18.0.0+
npm --version     # Should be v9.0.0+
```

### Test Connectivity

**Test 1 - Server Health:**
```bash
curl http://localhost:3001/api/turtles
```
Should return: `{"turtles":[]}`

**Test 2 - WebSocket:**
Open browser console and run:
```javascript
const ws = new WebSocket('ws://localhost:3002');
ws.onopen = () => console.log('Connected!');
ws.onerror = (e) => console.log('Error:', e);
```

**Test 3 - Minecraft HTTP:**
In ComputerCraft:
```lua
local r = http.get("http://localhost:3001/api/turtles")
print(r ~= nil)
```

---

**If all else fails:**
- Check the full README.md
- Review ARCHITECTURE.md for system design
- Ensure all dependencies are installed
- Try example commands manually
- Double-check all configuration files match

**Still stuck?** Create an issue with:
- Error messages
- Server/client logs
- Steps to reproduce
- Your configuration