Quick Reference: Troubleshooting

Fresh

Source: bible/setup.md, bible/runbook.md

Symptoms to fixes, one table.

Symptom	Fix
Server will not start (port in use)	Kill existing process on 4700 or change GHOST_ENGINE_PORT
Module not found	npm install
Node version error	Need Node 18+ (20+ recommended)
Accounts not importing	Check registryPath. Default: browser-sender/data/account-identity/registry.json
Cookie dir empty	Accounts work but need fresh login
Chrome not found	Install Google Chrome (not Chromium)
Profile locked	Another Chrome using profile. Close it
Ghost mode not working	Set VISION_PROVIDER + matching API key
Window not focused	Only one ghost session at a time on desktop
CTR not finding domain	Increase maxPages. If rank > 30, won't find
Wrong city for CTR	Verify city is in geo-profiles list
Too many failures	Reduce concurrency. Check proxy health
Rank not moving	Increase clicksPerDay. Add keyword variants. Layer cascades
Account attrition high	Reduce maxRunsPerAccount. Run warmup batches
CreepJS shows 33% headless	Verify --disable-blink-features=AutomationControlled flag, NO JS webdriver patch
ERR_SSL_PROTOCOL_ERROR	Disable TLS_PROXY (should be opt-in, not default)
Browser wrong size	Verify PHYSICAL_SCREEN = { width: 1366, height: 768 }
Account stuck COOLING	Force unlock: POST /accounts/:id/unlock
Proxy keeps rejecting	Pool fallback should auto-handle. Force rotate: POST /proxies/rotate
ADB device not detected	adb kill-server && adb start-server && adb devices
Server eats CPU at idle	Check /jobs/stats. Cancel stuck jobs. Disengage autopilot

Hard rules (do not break)

1. Do not patch navigator.webdriver via JS. Use the Chrome flag
2. Do not use big engine (:3500) for persona work
3. Do not pass windowSize or fingerprint from registry.json (stale macOS defaults)
4. Ghost mode is one desktop session at a time
5. Vision calls cost ~$0.003 each. Use only for navigation

Related

• Runbook Troubleshooting: full descriptions
• Recovery Recipes: step-by-step
• Anti-Detection