Troubleshooting

Common Issues

Characters Vanishing

Symptom: Characters disappear after page refresh Cause: Missing Privy credentials—each refresh creates a new anonymous identity Solution: Configure Privy authentication:

# packages/client/.env
PUBLIC_PRIVY_APP_ID=your-app-id

# packages/server/.env
PUBLIC_PRIVY_APP_ID=your-app-id
PRIVY_APP_SECRET=your-app-secret

Assets Not Loading

Symptom: 404 errors for models/avatars Cause: CDN container not running (development) or wrong CDN URL (production) Solutions: Development:

# Start CDN container
bun run cdn:up

# Verify CDN is serving manifests
curl http://localhost:8080/manifests/npcs.json

Production:

# Verify CDN URL is correct
echo $PUBLIC_CDN_URL
# Should be: https://assets.hyperscape.club

# Check server logs for manifest fetch errors
# Server fetches manifests at startup from CDN

Verify CDN is accessible:

# Test manifest fetch
curl https://assets.hyperscape.club/manifests/npcs.json

# Test model fetch
curl -I https://assets.hyperscape.club/models/goblin/goblin.vrm

Production:

Verify PUBLIC_CDN_URL is set correctly in server environment

Check manifests are publicly accessible:

curl https://assets.hyperscape.club/manifests/items.json

Check server logs for manifest fetch errors:

[Config] 📥 Fetching manifests from CDN: https://assets.hyperscape.club
[Config] ✅ items.json updated

Manifest fetch failures:

Server logs “Failed to fetch manifests from CDN”
Verify CDN URL is accessible
Check CORS headers allow server origin
In development, manifests can be local (skips CDN fetch)

Manifests Not Loading

Symptom: Server logs show “Failed to fetch manifests” or “No manifests available” Causes:

CDN not accessible at PUBLIC_CDN_URL
Manifests not deployed to CDN
Network connectivity issues

Solutions: Development:

# Ensure local manifests exist
ls packages/server/world/assets/manifests/

# If missing, clone assets repo
cd packages/server/world
git clone https://github.com/HyperscapeAI/assets.git

# Or start CDN
bun run cdn:up

Production:

# Verify CDN URL is correct
echo $PUBLIC_CDN_URL

# Test manifest accessibility
curl $PUBLIC_CDN_URL/manifests/npcs.json

# Check Railway logs for fetch errors
railway logs --filter manifest

Test Environment:

# Skip manifest loading for tests
SKIP_MANIFESTS=true bun test

Production: Verify PUBLIC_CDN_URL points to the correct R2 bucket:

Production: https://assets.hyperscape.club
Staging: https://staging-assets.hyperscape.club

Manifest Fetch Failures

Symptom: Server logs show “Failed to fetch manifests from CDN” Causes:

CDN URL incorrect or unreachable
R2 bucket not configured
Network connectivity issues

Solution: Development:

# Use local manifests (skip CDN fetch)
# Manifests already exist in packages/server/world/assets/manifests/
# Server will skip fetch if files exist locally

Production:

# Verify CDN URL is accessible
curl https://assets.hyperscape.club/manifests/npcs.json

# Check Railway logs for fetch errors
railway logs

# Manually upload manifests to R2 if missing
wrangler r2 object put "hyperscape-assets/manifests/npcs.json" \
  --file="packages/server/world/assets/manifests/npcs.json"

Test environment:

# Skip manifest fetching entirely
SKIP_MANIFESTS=true bun run dev
# or
NODE_ENV=test bun run dev

Database Schema Errors

Symptom: Errors about missing columns or tables Cause: Schema changed but migrations not run Solution:

cd packages/server
bunx drizzle-kit push

For a complete reset (destroys data):

docker stop hyperscape-postgres
docker rm hyperscape-postgres
docker volume rm hyperscape-postgres-data
docker volume rm server_postgres-data
bun run dev

Port Conflicts

Symptom: “Port already in use” errors Solution: Kill processes on conflicting ports:

lsof -ti:3333 | xargs kill -9   # Client
lsof -ti:5555 | xargs kill -9   # Server
lsof -ti:8080 | xargs kill -9   # CDN
lsof -ti:4001 | xargs kill -9   # ElizaOS

Build Errors

Symptom: Compilation fails Solution: Clean rebuild:

bun run clean
rm -rf node_modules packages/*/node_modules
bun install
bun run build

PhysX Build Fails

Symptom: Errors during PhysX compilation Cause: PhysX WASM build requires emscripten Solution: PhysX is pre-built and committed. If you must rebuild:

cd packages/physx-js-webidl
./make.sh   # Requires emscripten toolchain

Tests Failing

Symptom: Tests timeout or fail unexpectedly Causes:

Server running during tests
Stale test data
Port conflicts

Solution:

# Stop any running servers
lsof -ti:5555 | xargs kill -9

# Check logs
ls /logs/

# Run tests
npm test

WebSocket Connection Failed

Symptom: Can’t connect to game server Causes:

Server not running
Wrong port configuration
Firewall blocking
CORS issues

Solutions:

Verify server is running: lsof -i:5555
Check client config: PUBLIC_WS_URL
Ensure no firewall blocks
Verify CORS configuration includes your client domain

CORS Debugging:

# Check server logs for CORS errors
# Server automatically allows:
# - https://hyperscape.club
# - https://*.hyperscape.pages.dev
# - https://*.up.railway.app
# - http://localhost:*

# Add custom domain via environment variable
CLIENT_URL=https://your-domain.com

Hot Reload Not Working

Symptom: Changes don’t appear in browser Causes:

Build cache stale
Wrong directory

Solution:

bun run dev:reset

UI Windows Not Positioning Correctly

Symptom: Windows cluster in corner or overlap after resize Causes:

Saved layout from different screen size
Missing anchor data in saved layout
Mobile-to-desktop transition

Solution:

Press L to enter edit mode
Manually reposition windows
Save new layout
Or reset to default layout:

// In browser console
localStorage.removeItem('hyperscape-window-layout');
location.reload();

Drag-and-Drop Not Working

Symptom: Can’t drag items or windows Causes:

Edit mode not enabled (for windows)
Drop zone not registered
Race condition in drag state

Solution:

For windows: Press L to enable edit mode
For items: Ensure inventory panel is open
Check browser console for errors
Try refreshing the page

Trade Not Completing

Symptom: Trade stuck on confirmation screen Causes:

Players moved too far apart
Inventory full
Items no longer available

Solution:

Check distance to trade partner (must be within 2 tiles)
Free up inventory space
Verify items still in inventory
Cancel and restart trade if stuck

Logs

Server Logs

Check terminal output where bun run dev is running.

Test Logs

ls packages/server/logs/

Docker Logs

docker logs hyperscape-postgres
docker logs hyperscape-cdn

Deployment Issues

Railway Build Failing

Symptom: Railway deployment fails during build Common Causes:

Lockfile frozen error:

lockfile had changes, but lockfile is frozen

Solution: Regenerate lockfile locally and commit:

bun install
git add bun.lock
git commit -m "fix: update bun.lock"
git push

Out of memory during build: Solution: Railway provides 8GB RAM for builds. If exceeded, optimize build:

# Reduce concurrent builds in turbo.json
"pipeline": {
  "build": {
    "dependsOn": ["^build"],
    "outputs": ["dist/**", "build/**"]
  }
}

Missing environment variables: Solution: Verify all required vars are set in Railway dashboard:
- DATABASE_URL (auto-set if using Railway PostgreSQL)
- PRIVY_APP_ID and PRIVY_APP_SECRET
- PUBLIC_CDN_URL

Cloudflare Pages Build Failing

Symptom: Pages deployment fails Common Causes:

Build command not found: Solution: Ensure build command includes cd packages/client:
```
cd packages/client && bun install && bun run build
```
Environment variables not set: Solution: Add in Pages dashboard → Settings → Environment variables:
- PUBLIC_PRIVY_APP_ID
- PUBLIC_API_URL
- PUBLIC_WS_URL
- PUBLIC_CDN_URL
Build output directory wrong: Solution: Set to packages/client/dist in Pages settings

Manifest Fetch Errors

Symptom: Server logs show manifest fetch failures Causes:

CDN URL incorrect
R2 bucket not public
Manifests not uploaded to R2

Solutions:

# Verify CDN URL
curl $PUBLIC_CDN_URL/manifests/npcs.json

# Check R2 bucket permissions
# Bucket must allow public reads

# Re-upload manifests
wrangler r2 object put hyperscape-assets/manifests/npcs.json \
  --file=packages/server/world/assets/manifests/npcs.json

Frontend Can’t Connect to Backend

Symptom: Client shows “Connecting…” indefinitely Causes:

Wrong PUBLIC_API_URL or PUBLIC_WS_URL
CORS blocking requests
Railway server not running

Solutions:

Verify environment variables in Cloudflare Pages:

PUBLIC_API_URL=https://hyperscape-production.up.railway.app
PUBLIC_WS_URL=wss://hyperscape-production.up.railway.app/ws

Check Railway server status:

curl https://hyperscape-production.up.railway.app/status

Verify CORS configuration in server logs:

[HTTP] ✅ CORS configured for: https://hyperscape.club, https://www.hyperscape.club, ...

Test WebSocket connection:

// Browser console
const ws = new WebSocket('wss://hyperscape-production.up.railway.app/ws');
ws.onopen = () => console.log('Connected!');
ws.onerror = (e) => console.error('Error:', e);

Getting Help

Check GitHub Issues
Search existing discussions
Join Discord for community support
Open a new issue with:
- Error message (full stack trace)
- Steps to reproduce
- Environment details (OS, Node version, Bun version)
- Deployment platform (Railway, Cloudflare Pages, local)

Configuration

Operations

Common Issues

Characters Vanishing

Assets Not Loading

Manifests Not Loading

Manifest Fetch Failures

Database Schema Errors

Port Conflicts

Build Errors

PhysX Build Fails

Tests Failing

WebSocket Connection Failed

Hot Reload Not Working

UI Windows Not Positioning Correctly

Drag-and-Drop Not Working

Trade Not Completing

Logs

Server Logs

Test Logs

Docker Logs

Deployment Issues

Railway Build Failing

Cloudflare Pages Build Failing

Manifest Fetch Errors

Frontend Can’t Connect to Backend

Getting Help

Configuration

Operations

​Common Issues

​Characters Vanishing

​Assets Not Loading

​Manifests Not Loading

​Manifest Fetch Failures

​Database Schema Errors

​Port Conflicts

​Build Errors

​PhysX Build Fails

​Tests Failing

​WebSocket Connection Failed

​Hot Reload Not Working

​UI Windows Not Positioning Correctly

​Drag-and-Drop Not Working

​Trade Not Completing

​Logs

​Server Logs

​Test Logs

​Docker Logs

​Deployment Issues

​Railway Build Failing

​Cloudflare Pages Build Failing

​Manifest Fetch Errors

​Frontend Can’t Connect to Backend

​Getting Help

Common Issues

Characters Vanishing

Assets Not Loading

Manifests Not Loading

Manifest Fetch Failures

Database Schema Errors

Port Conflicts

Build Errors

PhysX Build Fails

Tests Failing

WebSocket Connection Failed

Hot Reload Not Working

UI Windows Not Positioning Correctly

Drag-and-Drop Not Working

Trade Not Completing

Logs

Server Logs

Test Logs

Docker Logs

Deployment Issues

Railway Build Failing

Cloudflare Pages Build Failing

Manifest Fetch Errors

Frontend Can’t Connect to Backend

Getting Help