Skip to main content

CI/CD Troubleshooting Guide

Overview

This guide documents common CI/CD issues, their root causes, and solutions based on recent fixes to the Hyperscape build pipeline.

Database Migration Issues

Issue: Migration 0050 Duplicate Table Errors

Symptom:
Cause (commit e4b6489):
  • Migration 0050 duplicated CREATE TABLE statements from earlier migrations
  • Example: agent_duel_stats was created in migration 0039 and again in 0050
  • On fresh databases, running all migrations sequentially caused duplicate table errors
Solution: Added IF NOT EXISTS to all CREATE TABLE and CREATE INDEX statements in migration 0050:
Prevention:
  • Always use IF NOT EXISTS for CREATE TABLE in migrations
  • Check migration history before adding new tables
  • Test migrations on fresh database before committing

Issue: FK Ordering in Sequential Migrations

Symptom:
Cause (commit eb8652a):
  • Migration 0050 references tables from older migrations (e.g., arena_rounds)
  • On fresh databases, FK constraints may fail if tables aren’t created in dependency order
  • Sequential migration execution doesn’t guarantee FK ordering
Solution: Use drizzle-kit push for declarative schema creation + SKIP_MIGRATIONS=true:
Why This Works:
  • drizzle-kit push creates schema declaratively (no ordering issues)
  • SKIP_MIGRATIONS=true tells server to skip built-in migration execution
  • Server starts with pre-created schema

Issue: drizzle-kit push + Server Migration Conflict

Symptom:
Cause (commit b5d2494):
  • Running drizzle-kit push creates tables without populating migration journal
  • Server’s built-in migration code tries to create tables again
  • Results in duplicate table errors
Solution: Do NOT run drizzle-kit push separately in CI. Let server handle migrations:

SKIP_MIGRATIONS Environment Variable

Purpose: Skip server migration when schema is created externally When to Use:
  • CI/testing environments using drizzle-kit push
  • External schema management tools
  • Integration tests that create schema before server startup
What It Skips (commit 6a5f4ee):
  • Built-in migration execution
  • hasRequiredPublicTables validation check
  • Migration recovery loop
Important: You MUST create the database schema externally before starting the server with SKIP_MIGRATIONS=true. Example:

Dependency Issues

Issue: ESLint ajv TypeError

Symptom:
Cause (commit b344d9e):
  • Root package.json forced ajv@8 via overrides
  • @eslint/eslintrc requires ajv@6 for Draft-04 schema support
  • Version conflict caused constructor chain to break
Solution: Remove ajv version overrides from root package.json:
Prevention:
  • Don’t force major version upgrades via overrides
  • Check package peer dependencies before overriding
  • Test ESLint after adding overrides

Issue: Missing hls.js Dependency

Symptom:
Cause (commit cfdabf3):
  • StreamPlayer.tsx imports hls.js but it was not declared in package.json
  • Works locally due to workspace hoisting
  • Fails in CI where bun resolves dependencies strictly
Solution: Add missing dependency to package.json:
Prevention:
  • Run bun install --frozen-lockfile to catch missing deps
  • Test builds in clean environment (Docker)
  • Use bun run build before committing

Issue: Foundry/Anvil Not Available in CI

Symptom:
Cause (commit b344d9e):
  • Integration tests require anvil binary for local Ethereum node
  • Foundry toolchain not installed in CI environment
Solution: Add Foundry toolchain to CI workflow:
Local Development:

Package Exclusions

Excluded from CI Tests

Packages:
  1. @hyperscape/contracts (commit 99dec96)
  2. @hyperscape/gold-betting-demo (commit 93f9633)
  3. @hyperscape/evm-contracts (commit 034f9c9)
Reasons:
  • contracts: MUD CLI + @trpc/server compatibility issue
  • gold-betting-demo: hls.js dependency resolution issue (fixed in cfdabf3, but still excluded)
  • evm-contracts: Foundry/anvil not available in CI
Turbo Filter:
Re-enabling: Tests will be re-enabled when dependency conflicts are resolved.

Chain Setup Issues

Issue: Chain Setup Fails in CI

Symptom:
Cause (commit 034f9c9):
  • setup-chain.mjs tries to start anvil and deploy MUD contracts
  • Anvil binary not available in CI environment
  • MUD CLI has compatibility issues
Solution: Skip chain setup when CI=true:
Local Development:

Asset Management

Issue: Assets Directory Already Exists

Symptom:
Cause (commit 6ce05cc):
  • CI workflow clones assets repo
  • Previous run left assets directory
  • Git clone fails on non-empty directory
Solution: Remove assets directory before cloning:
Prevention:
  • Always clean up in CI workflows
  • Use rm -rf before git clone
  • Consider using git clone --depth 1 for faster clones

Security Audit

Issue: Build Fails on High Severity Vulnerabilities

Symptom:
Cause (commit 19bebe2):
  • bigint-buffer has high severity vulnerability
  • No upstream patch available
  • CI audit threshold set to high
Solution: Lower audit threshold to critical:
Rationale:
  • Allows builds to pass while waiting for upstream fixes
  • Critical vulnerabilities still block builds
  • High/moderate vulnerabilities logged but don’t fail CI
Remaining Vulnerabilities:
  • bigint-buffer (high) - no patched version available
  • elliptic (moderate) - no patched version available

Recent Security Fixes (commit a390b79)

Resolved:
  • ✅ Playwright ^1.55.1 (fixes GHSA-7mvr-c777-76hp, high)
  • ✅ Vite ^6.4.1 (fixes GHSA-g4jq-h2w9-997c, GHSA-jqfw-vq24-v9c3, GHSA-93m4-6634-74q7)
  • ✅ ajv ^8.18.0 (fixes GHSA-2g4f-4pwh-qvx6)
  • ✅ Root overrides for: @trpc/server, minimatch, cookie, undici, jsondiffpatch, tmp, diff, bn.js, ai
Total: 14 of 16 vulnerabilities resolved

Documentation Updates

Issue: Mintlify API Failures Block CI

Symptom:
Cause (commit 034f9c9):
  • Mintlify service outages
  • API rate limits
  • Network issues
Solution: Add continue-on-error to docs update step:
Rationale:
  • Documentation updates are not critical for build success
  • Allows CI to continue even if docs API is down
  • Docs can be updated manually if needed

Build Resilience

Issue: Circular Dependencies Break Clean Builds

Symptom:
Cause (commit 5666ece):
  • Circular dependencies between packages
  • @hyperscape/shared imports from @hyperscape/procgen
  • @hyperscape/procgen peer-depends on @hyperscape/shared
  • When turbo runs clean build, tsc fails because the other package’s dist/ doesn’t exist yet
Solution: Use tsc || echo pattern for resilient builds:
Why This Works:
  • Build exits 0 even with circular dep errors
  • Packages produce partial output sufficient for downstream consumers
  • Turbo can continue build pipeline
Prevention:
  • Avoid circular dependencies when possible
  • Use peer dependencies carefully
  • Test clean builds: bun run clean && bun run build

TypeScript Errors

Issue: Type Errors Block CI

Symptom:
Cause (commit 5e60439):
  • Type mismatches after refactoring
  • Missing type casts
  • Private methods called from tests
Solutions: Type Casts:
Parameters Utility:
Visibility Changes:

Test Infrastructure

WebGPU Mocks for Three.js

Issue: Three.js WebGPU renderer requires browser globals Symptom:
Solution (commit 25ba63c): Create vitest.setup.ts with WebGPU mocks:
Configure in vitest.config.ts:

ArenaService Test Helpers

Issue: Cannot spy on private methods Solution (commit 25ba63c): Add protected passthrough methods:
Database Mock Helper:

Streaming Infrastructure

Issue: WebGPU Crashes on RTX 5060 Ti

Symptom:
Cause (commits 0257563, 30cacb0):
  • RTX 5060 Ti has broken Vulkan ICD on Vast.ai
  • WebGPU defaults to Vulkan backend
  • Vulkan initialization crashes Chrome
Solutions: 1. Use GL ANGLE Backend:
2. Remove RTX 5060 Ti from GPU Search:
3. Use System FFmpeg:

Issue: RTX 4090 WebGPU Performance

Symptom:
  • WebGPU works but performance is suboptimal
  • GL backend used instead of Vulkan
Solution (commit 80bb06e): Switch ANGLE to Vulkan backend for RTX 4090:
GPU-Specific Configuration:

Issue: Static FFmpeg Build SIGSEGV

Symptom:
Cause (commits 55a07bd, 536763d):
  • Static FFmpeg builds have compatibility issues
  • SIGSEGV during H.264 encoding
Solution: Use system FFmpeg instead of static build:
Verification:

Vast.ai Deployment

Issue: vastai CLI Not on PATH

Symptom:
Cause (commits 3ce7d64, 5c2a566):
  • vastai installed via pip but not on PATH
  • Python venv not activated
Solution: Use python venv for vastai install:
Alternative:

Issue: Python Version Too Old

Symptom:
Cause (commit 621ae67):
  • Debian bullseye-slim has Python 3.9
  • vastai-sdk requires Python 3.10+
Solution: Upgrade to Debian bookworm-slim:

Issue: PEP 668 Externally Managed Environment

Symptom:
Cause (commit d9e9111):
  • Debian 12 enforces PEP 668
  • System Python is externally managed
  • pip install blocked by default
Solution: Use --break-system-packages flag:
Better Solution: Use python venv (see above)

Playwright Issues

Issue: Chromium Not Installed

Symptom:
Cause:
  • Playwright browsers not installed
  • CI environment missing browser binaries
Solution:
CI Workflow:

Docker Issues

Issue: DNS Resolution Fails in Container

Symptom:
Cause (commit fd17248):
  • Container DNS not configured
  • Default resolv.conf doesn’t work
Solution: Overwrite resolv.conf with Google DNS:
Note: Use > for first line (overwrite), >> for subsequent lines (append)

Issue: Build Context Too Large

Symptom:
Solution: Add comprehensive .dockerignore:

CI Workflow Best Practices

Graceful Degradation

Principle: Non-critical steps should not fail the entire build Examples: Documentation Updates:
Asset Sync:

Conditional Execution

Skip Steps in CI:
Skip Steps Locally:

Caching Strategies

Bun Dependencies:
Playwright Browsers:

Debugging CI Failures

Enable Debug Logging

GitHub Actions:
Bun:

Reproduce Locally

Use CI Environment:
Docker Reproduction:

Inspect Artifacts

Save Logs:
Save Screenshots:

Common Error Patterns

Pattern: “Cannot find module”

Causes:
  1. Missing dependency in package.json
  2. Incorrect import path
  3. Build order issue (dependency not built yet)
Solutions:
  1. Add to dependencies: bun add <package>
  2. Fix import path
  3. Check turbo.json dependsOn

Pattern: “ECONNREFUSED”

Causes:
  1. Service not started
  2. Wrong port
  3. Service crashed
Solutions:
  1. Check service startup logs
  2. Verify port in .env
  3. Check for port conflicts: lsof -ti:5555

Pattern: “Timeout”

Causes:
  1. Service slow to start
  2. Network latency
  3. Deadlock
Solutions:
  1. Increase timeout
  2. Add retry logic
  3. Check for circular waits

Monitoring & Alerts

CI Failure Notifications

Slack Integration:
Discord Integration:

Health Checks

Server Health Endpoint:
CI Health Check:

Performance Optimization

Parallel Builds

Turbo Configuration:
Benefits:
  • Builds packages in parallel when possible
  • Respects dependency order
  • Caches outputs for incremental builds

Incremental Testing

Run Only Changed Tests:
Skip Unchanged Packages:

Rollback Procedures

Revert Failed Deployment

Railway:
Cloudflare Pages:

Database Rollback

Drizzle Migrations:
Important: Always backup before migrations in production

References

  • Commit e4b6489: Migration 0050 IF NOT EXISTS fix
  • Commit eb8652a: drizzle-kit push + SKIP_MIGRATIONS
  • Commit b344d9e: ESLint ajv fix + Foundry toolchain
  • Commit 25ba63c: WebGPU mocks + test helpers
  • Commit 034f9c9: Chain setup skip + docs continue-on-error
  • Commit 5666ece: Circular dependency resilience
  • Commit a390b79: Security audit fixes
  • CI Workflows: .github/workflows/