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:

   const PORT = 3005;  // Change from 3001
   const WS_PORT = 3006;  // Change from 3002
   

2. Edit client/src/store/turtleStore.js:

   const WS_URL = 'ws://localhost:3006';
   const API_URL = 'http://localhost:3005';
   

Solution 2 - Kill Existing Process:

Linux/Mac:

lsof -ti:3001 | xargs kill -9
lsof -ti:3002 | xargs kill -9

Windows:

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:

   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:

   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:

   gps host X Y Z
   

   Replace X Y Z with that computer's actual coordinates

5. Test from turtle:

   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:

   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:

   # Linux/Mac
   ifconfig | grep "inet "
   
   # Windows
   ipconfig
   

   Example: 192.168.1.100

2. Update configs to use IP instead of localhost:

   webbridge.lua:

   local SERVER_URL = "http://192.168.1.100:3001"
   

   client/src/store/turtleStore.js:

   const WS_URL = 'ws://192.168.1.100:3002';
   const API_URL = 'http://192.168.1.100:3001';
   

3. Configure firewall:

   Linux:

   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:

   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:

# 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

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

Test Connectivity

Test 1 - Server Health:

curl http://localhost:3001/api/turtles

Should return: {"turtles":[]}

Test 2 - WebSocket: Open browser console and run:

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:

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