> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

## 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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Start CDN container
bun run cdn:up

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

**Production:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

1. Verify `PUBLIC_CDN_URL` is set correctly in server environment
2. Check manifests are publicly accessible:
   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   curl https://assets.hyperscape.club/manifests/items.json
   ```
3. 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Use local manifests (skip CDN fetch)
# Manifests already exist in packages/server/world/assets/manifests/
# Server will skip fetch if files exist locally
```

**Production:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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**:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
cd packages/server
bunx drizzle-kit push
```

For a complete reset (destroys data):

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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**:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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**:

1. Verify server is running: `lsof -i:5555`
2. Check client config: `PUBLIC_WS_URL`
3. Ensure no firewall blocks
4. Verify CORS configuration includes your client domain

**CORS Debugging:**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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**:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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**:

1. Press **L** to enter edit mode
2. Manually reposition windows
3. Save new layout
4. Or reset to default layout:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// 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**:

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

## Logs

### Server Logs

Check terminal output where `bun run dev` is running.

### Test Logs

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
ls packages/server/logs/
```

### Docker Logs

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
docker logs hyperscape-postgres
docker logs hyperscape-cdn
```

## Deployment Issues

### Railway Build Failing

**Symptom**: Railway deployment fails during build

**Common Causes:**

1. **Lockfile frozen error**:

   ```
   lockfile had changes, but lockfile is frozen
   ```

   **Solution**: Regenerate lockfile locally and commit:

   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   bun install
   git add bun.lock
   git commit -m "fix: update bun.lock"
   git push
   ```

2. **Out of memory during build**:

   **Solution**: Railway provides 8GB RAM for builds. If exceeded, optimize build:

   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   # Reduce concurrent builds in turbo.json
   "pipeline": {
     "build": {
       "dependsOn": ["^build"],
       "outputs": ["dist/**", "build/**"]
     }
   }
   ```

3. **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:**

1. **Build command not found**:

   **Solution**: Ensure build command includes `cd packages/client`:

   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   cd packages/client && bun install && bun run build
   ```

2. **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`

3. **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**:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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**:

1. **Verify environment variables** in Cloudflare Pages:
   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   PUBLIC_API_URL=https://hyperscape-production.up.railway.app
   PUBLIC_WS_URL=wss://hyperscape-production.up.railway.app/ws
   ```

2. **Check Railway server status**:
   ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
   curl https://hyperscape-production.up.railway.app/status
   ```

3. **Verify CORS configuration** in server logs:
   ```
   [HTTP] ✅ CORS configured for: https://hyperscape.club, https://www.hyperscape.club, ...
   ```

4. **Test WebSocket connection**:
   ```javascript theme={"theme":{"light":"github-light","dark":"css-variables"}}
   // 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

1. Check [GitHub Issues](https://github.com/HyperscapeAI/hyperscape/issues)
2. Search existing discussions
3. Join [Discord](https://discord.gg/JD3MEwNbbX) for community support
4. 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)