Skip to content

Common Issues

Jump to bottom
Marc Sanchis edited this page Jun 5, 2025 · 1 revision

Common Issues and Solutions

Comprehensive troubleshooting guide for frequently encountered issues in the Hyperloop UPV Control Station system.

🚨 Critical Issues

Emergency Response Procedures

System Unresponsive

Symptoms: Control Station completely unresponsive, no sensor data

Immediate Actions:

  1. Check physical emergency stop - Verify E-stop hasn't been triggered
  2. Verify network connectivity - Check all ethernet cables and switches
  3. Restart backend server - Use emergency restart procedures
  4. Contact safety team - If vehicle is in operation

Recovery Steps:

# Emergency backend restart
cd backend/cmd
sudo pkill -f "./backend"
./backend

# Check system status
curl -s http://localhost:8080/health

Network Communication Lost

Symptoms: "Connection Lost" messages, no real-time data

Immediate Actions:

  1. Check network hardware - Switches, NAPs, routers
  2. Verify IP configuration - Ensure 192.168.0.9 is configured
  3. Test connectivity - Ping vehicle and booster networks
  4. Check wireless links - NAP status and signal strength

🔧 Backend Issues

Issue: Backend Won't Start

Symptoms:

  • Error on startup: "address already in use"
  • "config.toml not found" message
  • Permission denied errors

Solutions:

Port Already in Use

# Check what's using port 8080
netstat -tlnp | grep :8080
lsof -i :8080

# Kill existing process
sudo pkill -f backend
# or find PID and kill specifically
kill [PID]

Missing Configuration

# Verify config.toml exists
ls -la backend/cmd/config.toml

# Create default config if missing
cp backend/cmd/config.toml.example backend/cmd/config.toml

# Check ADJ directory exists
ls -la backend/cmd/adj/

Permission Issues

# Grant network capabilities (Linux)
sudo setcap cap_net_raw,cap_net_admin=eip ./backend

# Run with sudo (temporary fix)
sudo ./backend

# Check file permissions
chmod +x ./backend

Issue: Go Build Errors

Symptoms:

  • "module not found" errors
  • Version conflicts
  • Missing dependencies

Solutions:

# Update Go modules
cd backend
go mod tidy
go mod download

# Clear module cache
go clean -modcache

# Rebuild from scratch
go build -o backend cmd/main.go cmd/config.go cmd/pid.go cmd/trace.go

Issue: ADJ Loading Failures

Symptoms:

  • "BLCU address not found in ADJ"
  • Board registration failures
  • JSON parsing errors

Solutions:

# Check ADJ files exist
ls -la backend/cmd/adj/boards/

# Validate JSON syntax
cd backend/cmd/adj
find . -name "*.json" -exec python -m json.tool {} \; > /dev/null

# Update ADJ from git
git submodule update --init --recursive

🌐 Frontend Issues

Issue: Frontend Won't Load

Symptoms:

  • Blank page in browser
  • "Cannot connect to server" errors
  • Build failures

Solutions:

Development Server Issues

# Check Node.js version
node --version  # Should be 18+

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Start dev server with debugging
npm run dev -- --host 0.0.0.0 --port 5173

Build Issues

# Build common-front first
cd common-front
npm run build

# Then build control-station
cd ../control-station
npm run build

# Check for TypeScript errors
npm run typecheck

Browser Compatibility

  • Use Chrome/Firefox - Edge may have compatibility issues
  • Disable browser extensions - Some ad blockers interfere
  • Clear browser cache - Force refresh with Ctrl+F5
  • Check browser console - Look for JavaScript errors

Issue: WebSocket Connection Errors

Symptoms:

  • "WebSocket failed to connect"
  • Data not updating in real-time
  • Intermittent disconnections

Solutions:

# Test WebSocket directly
wscat -c ws://localhost:8080/ws

# Check firewall rules
# Windows
netsh advfirewall firewall show rule name="Hyperloop Backend"

# Linux
sudo iptables -L | grep 8080

# Test with telnet
telnet localhost 8080

🌐 Network Issues

Issue: No Network Connectivity

Symptoms:

  • Cannot ping other networks
  • "Network unreachable" errors
  • Timeouts on connections

Solutions:

IP Configuration Check

# Verify static IP is set
ip addr show  # Linux
ifconfig      # macOS
ipconfig /all # Windows

# Should see 192.168.0.9/24

Routing Problems

# Check routing table
ip route show       # Linux
route -n get default # macOS
route print         # Windows

# Test connectivity step by step
ping 192.168.0.1    # Local gateway
ping 192.168.1.1    # Vehicle network
ping 192.168.2.1    # Booster network

NAP Wireless Issues

# Check NAP status via web interface
# Access: http://192.168.0.101 (Control NAP)

# Test signal strength
iwconfig wlan0      # Linux
Airport -s          # macOS

# Restart NAP devices if needed
# Power cycle PoE injectors

Issue: High Network Latency

Symptoms:

  • Slow response from control commands
  • Delayed sensor data updates
  • Packet loss warnings

Solutions:

# Measure latency
ping -c 10 192.168.1.101
mtr 192.168.1.101  # Linux - shows hop-by-hop

# Check network utilization
iftop -i eth0       # Linux
nettop             # macOS

# QoS configuration on switches
# Prioritize control traffic

🔋 Hardware Issues

Issue: PoE Power Problems

Symptoms:

  • NAPs randomly disconnecting
  • LED indicators flickering
  • Intermittent connectivity

Solutions:

  1. Check power consumption - NAPs need 24W+ PoE
  2. Verify cable length - Max 100m for PoE
  3. Test with different injector - Rule out faulty equipment
  4. Check cable crimping - Poor connections cause power issues

Issue: Ethernet Cable Problems

Symptoms:

  • Intermittent connections
  • Reduced speed (100Mbps instead of 1Gbps)
  • High error rates

Diagnostic Steps:

# Check link speed
ethtool eth0        # Linux
networksetup -getinfo "Ethernet" # macOS

# Test cable with different devices
# Check for physical damage
# Verify proper termination

💾 Data and Storage Issues

Issue: Log Files Growing Too Large

Symptoms:

  • Disk space warnings
  • Slow system performance
  • "No space left on device" errors

Solutions:

# Check disk usage
df -h

# Find large files
find /var/log -type f -size +100M

# Rotate logs
logrotate -f /etc/logrotate.conf

# Clean old logs
find logs/ -name "*.log" -mtime +7 -delete

Issue: Configuration Corruption

Symptoms:

  • Backend starts with default settings
  • Settings not persisting
  • JSON parsing errors

Solutions:

# Backup current config
cp backend/cmd/config.toml backend/cmd/config.toml.backup

# Restore from backup
cp backend/cmd/config.toml.working backend/cmd/config.toml

# Validate configuration syntax
toml-test backend/cmd/config.toml

🔒 Security Issues

Issue: Authentication Failures

Symptoms:

  • Cannot access devices
  • "Access denied" messages
  • SSH connection refused

Solutions:

# Check SSH service
systemctl status ssh  # Linux
sudo launchctl list | grep ssh # macOS

# Test with verbose output
ssh -v admin@192.168.0.101

# Reset device passwords if needed
# Use console access for recovery

Issue: Firewall Blocking Traffic

Symptoms:

  • Connections timing out
  • Specific ports unreachable
  • Works locally but not remotely

Solutions:

# Linux iptables
sudo iptables -L
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

# Windows Firewall
netsh advfirewall firewall add rule name="Hyperloop Backend" dir=in action=allow protocol=TCP localport=8080

# macOS
sudo pfctl -sr

🧪 Development Issues

Issue: Cross-Platform Build Problems

Symptoms:

  • Builds work on one OS but not another
  • Path separator issues
  • Permission problems

Solutions:

# Use proper scripts for your platform
# Windows: scripts/dev.ps1 or scripts/dev.cmd
# Linux/macOS: scripts/dev.sh

# Check file permissions
chmod +x scripts/dev.sh

# Use Docker for consistent environment
docker-compose -f docker-compose.dev.yml up

Issue: Development Environment Conflicts

Symptoms:

  • Wrong Node.js/Go versions
  • Package conflicts
  • Path issues

Solutions:

# Check versions
node --version   # Should be 18+
go version      # Should be 1.21+

# Use version managers
nvm use 18      # Node Version Manager
gvm use go1.21  # Go Version Manager

# Clean environment
npm cache clean --force
go clean -cache

📊 Performance Issues

Issue: High CPU Usage

Symptoms:

  • System running slowly
  • Fan noise from computers
  • Response delays

Diagnostic Steps:

# Check processes
top
htop
ps aux | grep backend

# Monitor system resources
iostat 1
vmstat 1

# Check for memory leaks
valgrind ./backend

Issue: Memory Leaks

Symptoms:

  • Memory usage constantly increasing
  • System becoming unresponsive
  • Out of memory errors

Solutions:

# Monitor memory usage
free -h
watch -n 1 'free -h'

# Check for leaks in Go
go tool pprof http://localhost:8080/debug/pprof/heap

# Restart services regularly
systemctl restart hyperloop-backend

🔧 Quick Diagnostic Commands

System Health Check

#!/bin/bash
echo "=== Hyperloop System Health Check ==="

# Backend status
curl -s http://localhost:8080/health && echo "✅ Backend OK" || echo "❌ Backend Failed"

# Frontend status
curl -s http://localhost:5173 > /dev/null && echo "✅ Control Station OK" || echo "❌ Control Station Failed"
curl -s http://localhost:5174 > /dev/null && echo "✅ Ethernet View OK" || echo "❌ Ethernet View Failed"

# Network connectivity
ping -c 1 192.168.1.101 > /dev/null && echo "✅ Vehicle Network OK" || echo "❌ Vehicle Network Failed"
ping -c 1 192.168.2.101 > /dev/null && echo "✅ Booster Network OK" || echo "❌ Booster Network Failed"

# Disk space
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $DISK_USAGE -lt 80 ]; then
    echo "✅ Disk Space OK ($DISK_USAGE%)"
else
    echo "⚠️ Disk Space Warning ($DISK_USAGE%)"
fi

📞 Getting Help

Before Contacting Support

  1. Run the diagnostic commands above
  2. Check the logs for error messages
  3. Try the quick fixes listed for your issue
  4. Document the problem with screenshots/logs

Support Channels

  • GitHub Issues: software/issues
  • Emergency Contact: [Team safety procedures]
  • Documentation: This wiki and README files

Information to Provide

When reporting issues, include:

  • Exact error messages
  • System configuration (OS, versions)
  • Steps to reproduce the problem
  • Log files (backend.log, browser console)
  • Network configuration (IP addresses, topology)

🔗 Related Documentation

🔧 Remember: When in doubt, restart the backend server first - it resolves 80% of common issues!

Clone this wiki locally