Troubleshooting

Fixes for the problems that generate the most questions. When in doubt, run capium status first, it tells you whether the issue is your license, your host, or your code.

Diagnose first: capium status

Most launch failures are licensing or environment issues. capium status checks your key against the license service and prints your entitlements, or a precise error.

diagnose.sh

# Start here for any licensing or "won't start" issue.
python -m capium status
# Prints plan, sessions_cap, live_sessions, period_end — or a clear error.

License / activation errors

"no license configured" — set CAPIUM_LICENSE_KEY, pass license_key=, or create ~/.capium/license with a KEY= line. See Quickstart.
"rejected / expired / revoked" (CapiumExpiredError) — the key is invalid or the subscription lapsed. Check the dashboard on capzy.ai.
"session limit" (CapiumSeatLimitError) — you have as many concurrent browsers open as your plan allows. Close one and retry, or upgrade.
"server unreachable" (CapiumServerDownError) — the host can't reach license.capzy.ai. Check egress/firewall.

See the full Errors reference.

The browser won't launch

Missing OS libraries (Linux) — run python -m playwright install-deps.
No display — on a headless server, run headed under Xvfb rather than true headless.
Binary problems — pin a known-good build with CAPIUM_BINARY=/path/to/.../capium, or force a fresh download by clearing the cache.

host.sh

# Missing shared libraries on a fresh Linux box.
python -m playwright install-deps

# Run headed under a virtual display (recommended on servers).
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

Proxy failures

407 / auth failures — use the canonical inline form scheme://user:pass@host:port. For SOCKS5, credentials go in the URL too; see Proxies & geo.
Wrong country / timezone — turn on geoip=True so timezone, geo and the WebRTC IP follow the exit.
Leaks — verify with the leak check on the Verifying stealth page.

The persona doesn't look right

Isolate whether it's the persona or the target by launching in passthrough mode (seed="off") and comparing. If passthrough looks like your real host and a seeded launch does not, the persona is working; the issue is elsewhere (egress, behavior, or a host mismatch, see Verifying stealth).

isolate.py

from capium import launch_context

# Rule out the persona: seed="off" reports your host's real values.
browser, ctx, page = launch_context(seed="off", url="https://example.com")

Errors

FAQ