When automation fails, teams blame Playwright first. In Multilogin stacks, 80% of launch failures trace to proxy, zombie browser processes, or engine mismatch — not selectors. This runbook is the order senior engineers use before opening a vendor ticket.

Decision tree (first 5 minutes)

Profile start API fails?
  ├─ YES → Section A (API / auth / rate limit)
  └─ NO, but CDP attach fails?
       ├─ YES → Section B (CDP / timing / firewall)
       └─ NO, but site blocks / captcha?
            ├─ YES → Section C (fingerprint / proxy geo)
            └─ NO → Section D (automation code / race)

A — API & launcher layer

Symptom	Check	Fix
401 / 403	Token expiry, workspace scope	Rotate token; confirm profile folder ACL
429	Concurrent starts > limit	Semaphore 3–5 — production recipe
Start OK, empty CDP	Poll status endpoint	Wait up to 60s; see error codes
Stuck STARTING	Orphan Mimic process	Force stop API; kill local chrome/firefox PIDs

B — CDP attach layer

# Minimal CDP smoke test (Python)
import httpx
from playwright.sync_api import sync_playwright

PROFILE = "your-uuid"
TOKEN = "Bearer ..."
r = httpx.post("https://api.multilogin.com/profile/start",
    json={"profile_id": PROFILE, "headless": False},
    headers={"Authorization": TOKEN}, timeout=90)
cdp = r.json().get("cdp_url") or r.json().get("wsUrl")
assert cdp, f"No CDP: {r.text}"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp, timeout=60_000)
    page = browser.contexts[0].pages[0]
    page.goto("about:blank")
    print("CDP OK", page.url)
    browser.close()

httpx.post("https://api.multilogin.com/profile/stop",
    json={"profile_id": PROFILE}, headers={"Authorization": TOKEN})

Timeout 60s on connectOverCDP — cold Mimic boot needs it
Do not call browser.new_context() unless required — profile context already exists
WebSocket blocked — CI runners need localhost WS allowed

C — Mimic vs Stealthfox triage

Platform behavior	Try engine	Notes
Chromium-only sites, Google login	Mimic	Default for most web SaaS
Firefox-tolerant flows, some EU portals	Stealthfox	Different TLS/JA3 surface
Random crash on start	Clone profile, switch engine	Corrupt extension on one engine
Canvas/WebGL detection	Either + audit	Fingerprint audit script

Full engine comparison: Mimic vs Stealthfox.

D — Proxy & fingerprint

Pre-flight proxy: HTTP/SOCKS auth, geo, sticky session ID
Align timezone + language to proxy country — proxy alignment
Run automated audit vs profile manifest
Manual check: WebRTC, DNS leak on ipleak.net inside profile

Zombie process cleanup (Windows / Linux)

# Linux — find orphan Mimic/Chromium
ps aux | grep -E 'mimic|mlx|chromium' | grep -v grep
kill -9 <pid>   # after API force-stop failed

# Windows PowerShell
Get-Process | Where-Object {$_.Name -match 'mimic|chrome|firefox'} | Stop-Process -Force

What to log for every failed job

{
  "profile_id": "uuid",
  "engine": "mimic",
  "api_start_ms": 8420,
  "cdp_url_present": true,
  "cdp_connect_ms": 1200,
  "proxy_geo": "DE",
  "error_class": "CDP_TIMEOUT",
  "launcher_log_snippet": "..."
}

Structured logs let you correlate ban spikes with proxy pool rotations — not guess from one screenshot.

API error codes Fix automation blocks Pre-launch checklist Production recipe Code hub

Disclosure: MLX-MMO affiliated with Multilogin. API paths illustrative — verify against official docs.

Multilogin Profile Debugging Runbook