railway-debug

Railway Debug

Analyze Railway production logs, identify errors, and guide the fix for deploy and production issues.

Persistent memory: Check project memory for Railway-specific notes before any action.

---

Debug Workflow

0. CHECK MEMORY
   - Read project memory for Railway notes
   - Check known pitfalls and tested commands

1. COLLECT CONTEXT
   - railway status (project and environment)
   - Identify which service has the problem

2. ANALYZE LOGS
   - Runtime logs (production errors)
   - Build logs (deploy errors)
   - Filter by error level

3. ACCESS PRODUCTION DB (if needed)
   - Use public URL (switchyard.proxy.rlwy.net)
   - NEVER use internal hostname (.railway.internal)

4. IDENTIFY ROOT CAUSE
   - Categorize error type
   - Correlate with local code

5. PROPOSE AND APPLY FIX
   - Suggest specific fix
   - Apply fix in code
   - Validate locally before deploy

6. VERIFY FIX
   - Re-deploy
   - Confirm clean logs

7. UPDATE MEMORY
   - Save lessons learned

---

Railway CLI Commands (Tested and Working)

Commands that WORK

# General status (shows project, environment, current service)
railway status

# View variables for a specific service
railway variables --service <service-name>

# Execute command with Railway env vars injected
railway run -- node -e "console.log(process.env.DATABASE_URL ? 'ok' : 'no')"

# Runtime logs
railway logs -n 100 --service <service-name>

# Build logs
railway logs -n 200 --service <service-name> --build

# Redeploy
railway redeploy --service <service-name> --yes

# Variables as JSON (avoids table truncation)
railway variables --service <service-name> --json

Commands that DO NOT WORK (pitfalls)

# DOES NOT WORK: service list (does not exist)
railway service list        # "Service not found"

# DOES NOT WORK: railway run with psql (internal hostname)
railway run -- psql "$DATABASE_URL" -c "SELECT 1"
# Fails because DATABASE_URL = postgres.railway.internal (only resolves inside Railway)

# DOES NOT WORK: interactive prompts
railway service   # Requires TTY to select service

# DOES NOT WORK: railway link --service (requires TTY)
railway link --service <name>   # Can't be scripted