Troubleshooting Guide

This troubleshooting guide addresses common issues developers and users may encounter when working with the Chia Gaming system.

Developer Troubleshooting

Build and Deployment Issues

Docker Build Fails

Symptoms: The ./build-docker-images.sh command fails with errors.

Solutions:

• Check Docker Version: Ensure you have the latest Docker version. Install via Snap instead of apt if needed:

  sudo snap install docker

• Check Docker Permissions: Ensure your user is in the docker group:

  sudo usermod -aG docker $USER
  newgrp docker

• Check Disk Space: Ensure you have sufficient disk space for Docker images:

  df -h
  docker system df

• Clean Docker Cache: Try cleaning Docker's build cache:

  docker system prune -a

• Check Logs: Review the build output for specific error messages.

Containers Won't Start

Symptoms: Docker containers fail to start or immediately exit.

Solutions:

• Check Port Availability: Ensure ports 3000, 3001, and 5800 are not already in use:

  sudo lsof -i :3000
  sudo lsof -i :3001
  sudo lsof -i :5800

• Check Container Logs: View container logs for error messages:

  docker ps -a  # Get container IDs
  docker logs <container-id>

• Verify Configuration: Ensure all manual configuration steps have been completed correctly (see Manual Configuration).

Code Changes Not Reflecting

Symptoms: After making code changes, the changes don't appear when running the application.

Solutions:

• Rebuild Images: Code changes require rebuilding Docker images:

  ./build-docker-images.sh

• Check Build Output: Verify the build completed successfully and your changes were included.
• Restart Containers: Ensure containers were restarted after the build:

  docker ps  # Verify containers are running

Configuration Issues

WalletConnect Connection Fails

Symptoms: Unable to connect wallet via WalletConnect.

Solutions:

• Verify Project ID: Ensure your WalletConnect Project ID is correctly configured in resources/gaming-fe/src/constants/env.ts.
• Check Network Settings: Ensure you're using the correct network (testnet vs mainnet) and that the chain_id matches.
• WalletConnect Support: For WalletConnect registration and account issues, refer to the WalletConnect documentation and your WalletConnect account dashboard for troubleshooting.
• Review WalletConnect Guide: See the WalletConnect Developer Guide for detailed setup instructions.

Network Configuration Issues

Symptoms: Application can't connect to the blockchain via coinset.org.

Solutions:

• Verify Network Settings: Check that agg_sig_additional and chain_id are set correctly for your target network (testnet or mainnet).
• Test Network Connectivity: Verify the backend can reach coinset.org:

  # For mainnet
  curl https://coinset.org
  # For testnet
  curl https://testnet11.api.coinset.org

• Check Firewall: Ensure firewall rules allow outbound connections to coinset.org.
• Verify Content Security Policy: Check that CSP headers in resources/nginx/game.conf and resources/lobby-service/src/index.ts include the correct coinset.org URLs.

Port Configuration Issues

Symptoms: Can't access the application on expected ports.

Solutions:

• Check Port Bindings: Verify Docker port mappings are correct:

  docker ps  # Check port mappings

• Check Default Ports: Default ports are:
  • 3000: Frontend web interface
  • 3001: Lobby server API
  • 5800: Simulator service
• Check Port Availability: Ensure ports aren't already in use by another application.
• Review Port Documentation: See the Game Server and Lobby Server documentation for port configuration.

Development Environment Issues

Simulator Not Working

Symptoms: Simulator mode does not function correctly.

Solutions:

• Verify Simulator Enabled: Ensure the simulator option is enabled in the UI.
• Check Browser Console: Open browser developer tools and check for JavaScript errors.
• Verify Backend Connection: Ensure the game server is running and accessible.

Logs Not Appearing

Symptoms: Can not see application logs for debugging.

Solutions:

• View Docker Logs: Use Docker logs to view container output:

  docker logs -f <container-id>

• Check Log Levels: Verify log levels are set appropriately in the configuration.
• Check Container Status: Ensure containers are running:

  docker ps

User Troubleshooting

Connection Issues

WalletConnect Will Not Connect

Symptoms: Unable to connect Chia wallet via WalletConnect.

Solutions:

• Check Wallet Version: Ensure you are using Chia 2.5.7 or later.
• Check Wallet Sync: Verify your wallet is synced with the blockchain.
• Clear WalletConnect Cache: Use the option in the UI to clear the WalletConnect cache, then try connecting again.
• Try Reconnecting: Disconnect and reconnect WalletConnect.
• Check Browser: Try a different browser or clear browser cache.
• Verify Network: Ensure you're on the correct network (testnet vs mainnet) that matches the game server configuration.
• WalletConnect Support: For WalletConnect-specific issues, refer to the WalletConnect documentation and your WalletConnect account dashboard for troubleshooting.

Handshake Never Completes

Symptoms: Handshake process seems to hang or never completes.

Solutions:

• Check for Pending WalletConnect Requests: Check your Chia wallet for any pending WalletConnect requests. The wallet may have a request waiting for approval that needs to be confirmed before the handshake can proceed. This is a common cause of handshake delays.
• Wait Longer: Handshaking requires 2 on-chain transactions. Each blockchain peak takes approximately 1 minute, so expect several minutes of waiting.
• Check Handshake Status: Look for on-screen status indicators showing handshake progress.
• Verify Wallet Connection: Ensure both players' wallets are properly connected and synced.
• Check Network: Verify both players have network connectivity and can reach coinset.org.
• Try Restarting: If handshake has been waiting for an unusually long time (10+ minutes), try restarting the connection.

Gameplay Issues

Game Won't Start

Symptoms: After handshake completes, game doesn't begin.

Solutions:

• Check Browser Console: Open browser developer tools (F12) and check for errors.
• Verify Both Players Connected: Ensure both players have successfully connected their wallets.
• Check Balance: Verify both players have sufficient balance for the game stake.
• Refresh Page: Try refreshing the page and reconnecting.

Cards or Game Elements Not Displaying

Symptoms: Game interface appears but cards or other elements are missing.

Solutions:

• Check Browser Compatibility: Ensure you're using a modern, supported browser (Chrome, Firefox, Safari, Edge).
• Clear Browser Cache: Clear your browser cache and reload the page.
• Check JavaScript: Ensure JavaScript is enabled in your browser.
• Check Console: Open browser developer tools and check for JavaScript errors.

Game Freezes or Becomes Unresponsive

Symptoms: Game stops responding to input or freezes.

Solutions:

• Check Network Connection: Verify you have a stable internet connection.
• Refresh Page: Try refreshing the page (note: this may end the current game session).
• Check Browser Console: Look for error messages in the browser console.
• Wait for Opponent: Some game states require waiting for the opponent's action.

Session Management Issues

Can Not End Session

Symptoms: Unable to end a game session.

Solutions:

• Wait for Current Hand: Complete or forfeit the current hand/game before ending the session.
• Check Balance: If ending due to insufficient balance, ensure the session can be properly closed.
• Wait for Opponent: If opponent is still active, wait for them to complete their turn or end their session.

Session Ends Unexpectedly

Symptoms: Game session ends without user action.

Possible Causes:

• Insufficient Balance: One or both players may have insufficient balance to continue.
• On-Chain Transaction: Session may have moved on-chain, requiring session end.
• Opponent Ended: The opponent may have ended the session.
• Network Issues: Network connectivity problems may have caused the session to end.

Solutions:

• Check End Screen: The end screen will show the reason for ending.
• Verify Balance: Ensure you have sufficient balance for the game stake.
• Check Network: Verify network connectivity is stable.

Getting Additional Help

If you continue to experience issues after trying these troubleshooting steps:

1. Check Known Issues: Review the Known Issues document for documented problems and workarounds.

2. Review Documentation:

   • Developers Guide
   • Users Guide

3. Check Repository: Review the chia-gaming repository for additional information and issue reports.

4. Support: For additional support, visit the Gaming channel in the official Chia Discord server.