Skip to main content
This guide covers common issues you may encounter when setting up or playing Elemental Battlecards, along with detailed solutions.

​
Connection Issues

Symptoms:
  • Frontend shows connection errors
  • Room creation fails
  • “Unable to connect” messages in browser console
Possible Causes:
  • Backend server is not running
  • Backend running on wrong port
  • Firewall blocking connections
  • Incorrect IP address
  • Network isolation (different subnets)
Solutions:
1

Verify Backend is Running

Check that the backend server is running:
curl http://localhost:3001/ping
Expected response:
{"ok":true,"time":1234567890,"host":"localhost"}
If this fails, start the backend:
cd Backend
npm start
2

Check Port Configuration

Verify the backend is running on port 3001:Windows:
netstat -ano | findstr :3001
Linux/Mac:
lsof -i :3001
You should see a Node.js process listening on port 3001.
3

Verify Network Connectivity

From the guest computer, test connectivity to the host:
ping 192.168.1.100
curl http://192.168.1.100:3001/ping
If ping works but curl fails, it’s a firewall issue.
4

Configure Firewall

Windows Firewall:
# Allow port 3001 (Backend)
netsh advfirewall firewall add rule name="Elemental Battlecards Backend" dir=in action=allow protocol=TCP localport=3001

# Allow port 5173 (Frontend)
netsh advfirewall firewall add rule name="Elemental Battlecards Frontend" dir=in action=allow protocol=TCP localport=5173
Linux (ufw):
sudo ufw allow 3001/tcp
sudo ufw allow 5173/tcp
sudo ufw reload
Mac:
# Go to System Preferences > Security & Privacy > Firewall
# Click "Firewall Options"
# Add Node.js to allowed applications
5

Check Network Isolation

Ensure both computers are on the same network:
  • Connected to same WiFi network
  • Both on same subnet (e.g., 192.168.1.x)
  • Not separated by VLANs
  • Not using VPN on either machine
Some public WiFi networks isolate devices from each other for security. Use a private home network for LAN play.
Symptoms:
  • “Sala no encontrada” error message
  • Unable to join room with 6-digit code
  • Join attempt fails silently
Possible Causes:
  • Incorrect room code
  • Room was deleted or expired
  • Host closed browser
  • Backend was restarted
Solutions:
1

Verify Room Code

Double-check the 6-digit code:
  • No typos or transposed numbers
  • Correct spacing (123 456, not 12 3456)
  • Code is still valid
2

Check Host Status

Ensure the host player:
  • Has not closed their browser tab
  • Is still on the room creation screen
  • Can see “Esperando jugador…” message
3

Recreate Room

If the room was lost:
  1. Host clicks back to home screen
  2. Host creates a new room
  3. Host shares the new 6-digit code
  4. Guest joins with new code
4

Check Backend Logs

Review backend console for errors:
# Look for room creation messages
# Check for Socket.IO connection events
If backend was restarted, all rooms are lost (stored in memory).
Symptoms:
  • “Sala llena” error message
  • Cannot join existing room
Cause: Each room supports exactly 2 players. A third player cannot join.Solution:
  • Host must create a new room for different players
  • Current players must leave the room first
  • Use different room codes for different pairs of players
This is by design. Elemental Battlecards is a 1v1 game, so each room is limited to 2 players.

​
Synchronization Issues

Symptoms:
  • Cards played on one client don’t appear on the other
  • Attacks or fusions don’t register
  • Delayed or missing game state updates
  • Turn timer out of sync
Possible Causes:
  • Network latency or packet loss
  • Socket.IO connection degraded
  • Browser performance issues
Solutions:
1

Check Network Stability

Test network latency:
ping -t 192.168.1.100  # Windows
ping 192.168.1.100     # Linux/Mac
Look for:
  • Consistent ping times (< 10ms on LAN)
  • No packet loss
  • No timeout errors
If you see packet loss or latency > 100ms, check your WiFi signal strength or use Ethernet cables.
2

Check Browser Console

Open browser developer tools (F12) and check the Console tab:Look for:
  • Socket.IO connection errors
  • Failed event emissions
  • JavaScript errors during game actions
Common messages:
  • "Socket connected" - Good
  • "Socket disconnected" - Connection lost
  • "Error emitting event" - Action failed
3

Restart Connection

  1. Both players close the game tab
  2. Host restarts backend (Ctrl+C, then npm start)
  3. Host creates new room
  4. Both players rejoin
This clears any stuck socket connections.
4

Check System Performance

Ensure adequate system resources:
  • Close unnecessary browser tabs
  • Check CPU usage (Task Manager / Activity Monitor)
  • Verify at least 2GB free RAM
  • Disable browser extensions that may interfere
Symptoms:
  • Both players can act simultaneously
  • Turn timer not counting down
  • “Tu turno” / “Turno del oponente” not displaying correctly
Cause: Game state synchronization issueSolution:
1

Verify Initial Sync

When both players join:
  • Host should see “Tu turno” immediately
  • Guest should see “Turno del oponente”
  • Timer should show 12 seconds
2

Check Socket Events

In browser console (F12), verify:
// Should see events like:
// turnStart
// turnEnd
// gameStateUpdate
3

Force State Refresh

If turns are stuck:
  1. Player whose turn it is should play a card
  2. This triggers a state update
  3. Turn should properly switch after action
If this doesn’t work, restart the match.

​
Database Issues

Symptoms:
  • “No se pudo conectar a la BD” error
  • Backend crashes on startup
  • Authentication routes not working
For PostgreSQL Users:
1

Verify PostgreSQL is Running

Windows:
Get-Service postgresql*
Linux:
sudo systemctl status postgresql
Mac:
brew services list | grep postgresql
2

Check Connection Details

Verify .env file:
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=elemental
DB_USER=postgres
DB_PASS=your_password
Test connection:
psql -h 127.0.0.1 -p 5432 -U postgres -d elemental
3

Switch to SQLite

For quick testing, use SQLite instead:
.env
DB_USE_SQLITE=true
DB_ENABLED=false
Restart the backend. SQLite requires no external database server.
For SQLite Users:No configuration needed! SQLite uses in-memory storage and requires no setup.
If you’re experiencing database issues during LAN play, consider disabling authentication entirely with DB_ENABLED=false.

​
Performance Issues

Symptoms:
  • Low frame rate
  • Laggy card animations
  • Delayed input response
Solutions:
1

Check Browser Compatibility

Recommended browsers:
  • Chrome 90+
  • Firefox 88+
  • Edge 90+
  • Safari 14+
Avoid Internet Explorer - it does not support modern WebGL features required by Phaser.
2

Enable Hardware Acceleration

Chrome/Edge:
  1. Go to chrome://settings
  2. Search for “hardware acceleration”
  3. Enable “Use hardware acceleration when available”
  4. Restart browser
3

Reduce Browser Load

  • Close unused tabs
  • Disable resource-heavy extensions
  • Clear browser cache
  • Close other applications
4

Check System Resources

Minimum requirements:
  • 4GB RAM
  • Integrated graphics or better
  • Dual-core CPU
Monitor usage during gameplay:
  • Task Manager (Windows)
  • Activity Monitor (Mac)
  • System Monitor (Linux)

​
Port Conflicts

Symptoms:
  • Error: listen EADDRINUSE: address already in use :::3001
  • Backend fails to start
  • Frontend dev server fails to start
Solution:
1

Find Process Using Port

Windows:
netstat -ano | findstr :3001
taskkill /PID <PID> /F
Linux/Mac:
lsof -ti:3001 | xargs kill -9
2

Use Different Port

Change port in .env:
PORT=3002
If you change the backend port, you must manually configure the frontend to use the new port via ?backend=http://localhost:3002 query parameter or window.BACKEND_URL.

​
General Debugging

To get more detailed error information:Backend:
.env
NODE_ENV=development
Frontend: Open browser console (F12) and check:
  • Console tab for JavaScript errors
  • Network tab for failed HTTP/WebSocket requests
  • Application tab for storage issues
If all else fails, perform a clean installation:
1

Backend

cd Backend
rm -rf node_modules package-lock.json
npm install
2

Frontend

cd Frontend
rm -rf node_modules package-lock.json dist
npm install
3

Clear Browser Data

  1. Open DevTools (F12)
  2. Application tab > Clear storage
  3. Clear all data
  4. Hard refresh (Ctrl+Shift+R)

​
Getting Help

If you’re still experiencing issues:
  1. Check browser console (F12) for error messages
  2. Review backend logs for connection or database errors
  3. Test the health endpoint: curl http://localhost:3001/ping
  4. Verify both computers are on the same network with ping
  5. Check firewall rules are properly configured
Most issues are related to network configuration or firewall settings. Double-check these first before investigating other causes.

Build docs developers (and LLMs) love

Get started for freeTalk to us