Skip to main content

Troubleshooting

Developer Troubleshooting​

Build Issues​

Rust / WASM​

wasm-pack not found or wrong version:

cargo install wasm-pack --version 0.15.0

WASM build fails with clang errors (macOS):

brew install llvm
# Build scripts auto-detect Homebrew LLVM paths

wasm32-unknown-unknown target not installed:

rustup target add wasm32-unknown-unknown

Node.js / pnpm​

pnpm not found or wrong version:

corepack enable
corepack prepare [email protected] --activate

ERR_PNPM_IGNORED_BUILDS warnings:

This is harmless. Silence with:

cd front-end && pnpm approve-builds
cd hub && pnpm approve-builds

Node version too old:

The project requires Node.js 22+. Check your version with node --version.

Chialisp / Hex Files​

Missing compiled CLVM artifacts:

./tools/build-chialisp.sh

This recompiles all .clsp sources (same script used by run-local-demo.sh and tools/build-deploy.sh). The compiler emits .hex and then .clvm.bin runtime artifacts.

Runtime Issues​

Simulator​

Simulator not responding on port 5800:

# Build and run the simulator
cargo build --features sim-server --bin chia-gaming-sim
./target/debug/chia-gaming-sim

The simulator uses a single port: 5800 for HTTP (GET|POST /health) and WebSocket (/ws). Ensure nothing else is using this port.

Port conflicts with hub:

The hub defaults to port 5801 if PORT is not set. Always set PORT explicitly:

From a source checkout (local demo):

PORT=3003 node hub/hub-service/dist/index-rollup.cjs --self 'http://localhost:3003' --dir ./hub/hub-frontend/serve

From a release zip (service.js at the archive root):

PORT=3003 node service.js --self 'http://localhost:3003' --dir /path/to/extracted-hub-archive

Player App​

Blank page or JS errors:

  • Verify WASM files exist in front-end/dist/ (chia_gaming_wasm.js, chia_gaming_wasm_bg.wasm)
  • Verify Chialisp build artifacts exist (run ./tools/build-chialisp.sh)
  • Check browser console for 404 errors on assets

build-meta.json errors:

The player app reads build-meta.json from the server root to determine the asset base path. If this file is missing or malformed, assets will fail to load. The run-local-demo.sh script generates this automatically.

Hub​

Hub iframe not loading:

  • Verify the hub is running on a different origin from the player app
  • Check the browser console for CSP (Content Security Policy) errors
  • Verify the --self flag matches the public URL of the hub
  • Electron: the hub origin must be on the desktop allowlist (hubOrigins in the app config.json, or typed into the in-app picker). A newly trusted hub reloads the window once. See desktop/README.md.

WebSocket connection failures:

  • Verify the hub's --self URL is accessible from both players' browsers or desktop apps
  • Check for firewall or proxy rules blocking WebSocket upgrades
  • Ensure the hub process is still running

WalletConnect Issues​

Connection​

WalletConnect pairing fails:

  • Ensure the Chia wallet is 2.7.1 or later (minimum)
  • Check that the wallet's WalletConnect feature is enabled
  • Confirm the player-app network setting matches the wallet (mainnet or testnet11)
  • Try regenerating the pairing URI by refreshing the player app

"No matching key" or namespace errors:

The gaming system requires specific WalletConnect methods. Ensure your wallet supports the chia namespace with the required methods. See front-end/src/constants/wallet-connect.ts in the repository for the full list.

During Gameplay​

Handshake hangs:

  1. Check your Chia wallet for pending approval requests
  2. Confirm each wallet is connected, synced, and has no pending WalletConnect approvals
  3. Check the browser console for WebSocket errors
  4. Ensure both players are connected to the same hub and the same network

Transaction not confirming:

  • Each transaction block takes approximately 1 minute
  • Channel opening uses one on-chain spend bundle; confirmation can take several minutes (about 1 minute per peak)
  • For live WalletConnect play, check the Transaction fee in the player app Wallet tab. The default is 100,000,000 mojos (0.0001 XCH). You can set 0. A nonzero fee below 100,000,000 mojos is treated as zero and can be rejected (INVALID_FEE_TOO_CLOSE_TO_ZERO)
  • If the UI warns that the configured fee was not applied, the protocol spend was still submitted without a fee (the wallet could not sign the fee offer)
  • If a transaction is stuck, check the mempool via your wallet

Wallet disconnects mid-game:

  • Reconnect the same wallet account via WalletConnect; stalled operations resume when that wallet is back (CONNECTIVITY.md)
  • If a different account is connected, the app shows a mismatch and will not apply funding or cleanup to it
  • Session data remains in IndexedDB across a page reload; do not clear site data during an active session
  • If the session is abandoned, channel coins follow on-chain timeout rules (see Known Issues)

Cloud Wallet button unavailable or incomplete:

  • Cloud Wallet is disabled in the UI (Cloud Wallet is temporarily unavailable)
  • Use Link Wallet (WalletConnect) for live play

Desktop installer blocked by the OS:

  • 0.4.0-beta.1 macOS and Windows installers are unsigned; Gatekeeper and SmartScreen warnings are expected
  • Verify the file against SHA256SUMS-mac.txt or SHA256SUMS-win.txt on 0.4.0-beta.1 before allowing it

User Troubleshooting​

For documented limitations and workarounds, see Known Issues.

Connection Issues​

Shutdown hangs or incomplete:

  • Both players should keep the app open until shutdown completes
  • Check each wallet for pending WalletConnect approvals

Session Management Issues​

Resume Session / Start over after reload:

  • A normal reload should restore the session from IndexedDB
  • If the previously-saved-state dialog appears, choose Resume Session unless you intend to abandon the local copy
  • Clearing site data cannot be undone from the server; channel coins may remain on-chain until timeout if you abandon mid-game

Firewall / Proxy​

WebSocket connections blocked:

  • Ensure your network allows WebSocket connections (HTTP Upgrade)
  • If behind a corporate proxy, WebSocket traffic may be blocked
  • The hub uses standard HTTP ports; configure your proxy to allow WebSocket upgrades on the hub's port

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:

  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.