Skip to content

Troubleshooting

Common issues, their causes, and how to fix them.

Panel Issues

"Sign in with Steam" does nothing

Cause Fix
API gateway not running Start with cd panel/api && node server.js
Gateway port blocked Check firewall: sudo ufw allow 3081
Nginx not proxying /auth/ Add location /auth/ { proxy_pass http://127.0.0.1:3081; }

Steam login redirects but panel shows error

Cause Fix
GATEWAY_URL mismatch Set to your panel's public URL (e.g., https://panel.qs-zuq.com)
SSL certificate issue Verify certbot certificate is valid: sudo certbot certificates
Steam API down Check Steam Status — retry later

"Not an admin" after Steam login

Cause Fix
No admin_role row for your Steam ID Bootstrap: ./panel/bootstrap-admin.sh
Wrong Steam ID format Must be Steam:STEAM64_ID (17-digit number, not STEAM_0:1:...)

Dashboard shows but no live data

Cause Fix
SpacetimeDB not running Start: spacetime start
VITE_STDB_HOST wrong Rebuild panel with correct WebSocket URL
WebSocket blocked Ensure nginx proxies /stdb/ with Upgrade headers
Module not published Publish: spacetime publish qs-bridge

"STDB not connected" on admin actions

Cause Fix
Gateway can't reach SpacetimeDB Check STDB_HOST in gateway .env
Invalid STDB_TOKEN Regenerate: spacetime identity token
Module crashed Check: spacetime logs qs-bridge

Session expired

Cause Fix
8-hour JWT expiry Sign in again — this is expected behaviour
Clock skew between gateway and browser Sync system clock: sudo ntpdate -s time.nist.gov

Bridge Issues

Bridge doesn't connect to SpacetimeDB

Cause Fix
QSB_STDB_HOST wrong Check the URL, ensure ws:// prefix
Firewall blocking port 3000 Open on VPS: sudo ufw allow 3000
SpacetimeDB not running Start: spacetime start
DNS resolution Use IP address instead of hostname

Server starts but bridge doesn't load

Cause Fix
LD_PRELOAD path wrong Use absolute path: LD_PRELOAD=/opt/qs-bridge/libqsbridge.so
Missing shared libraries Check: ldd /opt/qs-bridge/libqsbridge.so
Architecture mismatch Bridge must be built for same arch as game server (x86_64)
Permission denied Check file permissions: chmod 755 libqsbridge.so

Bridge connects but no data appears

Cause Fix
QSB_SERVER_ID not set Set environment variable before starting server
Module name mismatch QSB_STDB_MODULE must match published module name
HMAC secret mismatch QSB_HMAC_SECRET must match between bridge and STDB module

Bridge crashes on startup

Cause Fix
Game engine version mismatch Engine adapter must match exact game version
vtable offsets changed Game server updated — rebuild bridge with new offsets
Memory corruption Check dmesg for segfault details, review memory offsets

SpacetimeDB Issues

spacetime publish fails

Cause Fix
WASM build failed Run spacetime build first, check Rust errors
Module already exists Use spacetime publish --clear-database qs-bridge (⚠ deletes data)
Server not running Start: spacetime start
Rust target missing Install: rustup target add wasm32-unknown-unknown

Module crashes (reducer panics)

# Check module logs
spacetime logs qs-bridge

# Common causes:
# - Primary key conflict (inserting duplicate row)
# - Unwrap on None (table lookup miss)
# - Schema mismatch after update

Database grows too large

Action Command
Check size du -sh ~/.spacetimedb/
Clear module data spacetime publish --clear-database qs-bridge
Prune audit logs Write a reducer to delete old PanelAuditLog rows

Nginx Issues

502 Bad Gateway

Cause Fix
Backend not running Start the API gateway or SpacetimeDB
Wrong proxy_pass port Verify ports match service configuration

WebSocket connection fails

Ensure nginx config includes WebSocket upgrade headers:

location /stdb/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

SSL certificate expired

# Check certificate status
sudo certbot certificates

# Renew
sudo certbot renew

# Force renewal
sudo certbot renew --force-renewal

BisectHosting Issues

Lifecycle actions return 401

Cause Fix
Invalid API key Generate a new key in BisectHosting control panel
API key expired Regenerate and update .env

Lifecycle actions return 429

Cause Fix
Rate limited by QS-Bridge Wait 60 seconds between actions per server
Rate limited by BisectHosting Wait for BisectHosting's rate limit to reset

Server UUID not found

Cause Fix
Wrong hosting_id Verify UUID in BisectHosting dashboard
Server not on this account API key must belong to the account that owns the server

Diagnostic Commands

# Check all services
systemctl status spacetimedb qs-gateway nginx

# SpacetimeDB
spacetime sql qs-bridge "SELECT * FROM server_registry"
spacetime sql qs-bridge "SELECT * FROM module_config"
spacetime logs qs-bridge --tail 50

# Gateway
curl -s http://localhost:3081/api/health | jq .
journalctl -u qs-gateway --since "1 hour ago"

# Nginx
sudo nginx -t                    # Test config
sudo tail -50 /var/log/nginx/error.log

# Bridge
journalctl -u gameserver --since "1 hour ago" | grep -i qsbridge
ldd /opt/qs-bridge/libqsbridge.so

# Network
ss -tlnp | grep -E '3000|3081|443|80'
curl -s -o /dev/null -w "%{http_code}" https://panel.qs-zuq.com

Getting Help

If the issue isn't listed here:

  1. Check SpacetimeDB logs: spacetime logs qs-bridge
  2. Check gateway logs: journalctl -u qs-gateway
  3. Check the Roadmap for known issues
  4. File a bug on the project repository