Troubleshooting

The error → cause → fix matrix, grown from the field. Found something new? Add a row — one line can save the next person an afternoon.

Rule: version-stamp anything version-specific (e.g. "fixed in v0.8.1").

Engine & startup

Symptom	Cause	Fix
`engine ghostfox/camoufox binary not found`	`GHOSTFOX_HOME` doesn't point at the unpacked engine dir	Set `GHOSTFOX_HOME` to the dir containing `ghostfox-bin`. Python users: run `ghostfox.install_engine()` once.
`juggler: timeout waiting for Browser.enable`	Engine boot is slow on a loaded host — OR the Firefox userns fork-probe hangs under load (1-thread engine, stuck in `wait4`)	Wait it out (bootstrap allows 120s on ≥ 0.8.2-dev; old versions gave up at 20s). For the probe hang: set `MOZ_ASSUME_USER_NS=0` in the runtime's environment — it skips the fragile probe entirely.
Engine exits silently right after spawn on a remote-desktop host (VNC/NoMachine/X2Go)	Headless spawn inherited `DISPLAY` and coupled to the live desktop session	≥ 0.8.2-dev strips `DISPLAY`/`WAYLAND_DISPLAY` automatically. On older versions, unset them when launching. Do NOT strip `LD_PRELOAD` — required libs can route through it.
`libxul.so: version NSS_3.101 not found` when running the engine outside its dir	The engine resolves bundled libs relative to its own directory	Always launch `ghostfox-bin` with its install dir as the working directory (the runtime does this automatically).

Symptom	Cause	Fix
Digits and punctuation silently dropped in Lexical-based editors (X, Facebook, Notion)	Fixed in v0.8.1 — the runtime fabricated invalid DOM `code` values ("Key0", "Key.") that Firefox's TextInputProcessor reads as non-printable	Upgrade to ≥ 0.8.1
Typing unicode (em-dash, CJK, emoji) does nothing	Old builds had no path for non-US-layout characters	≥ 0.8.1 routes them through Juggler `Page.insertText`

Symptom	Cause	Fix
Model auto-download fails at first captcha use	The models download from the v0.6.7 release assets	Check network access to `github.com/autokeren/ghostfox/releases/download/v0.6.7/...`, or grab them manually into `$GHOSTFOX_HOME/models/`.
Model outputs are all `1.0` (e.g. every siamese similarity identical)	Dynamically-quantized ONNX models fail silently in rten	Use dequantized (float) models — the shipped ones are already float. If porting new models: dequantize first.
OCR reads garbage on normal captchas	The ddddocr charset must match the model (`charset.txt`, CHARSET_BETA)	Use the shipped pair from `models/ddddocr/`; don't mix model/charset versions.

Symptom	Cause	Fix
Injected cookies don't take effect	Firefox 152 `cookies.sqlite` schema is picky: `expiry` is MILLISECONDS (Playwright storageState gives seconds — multiply by 1000), `schemeMap` must be `256`, `lastAccessed`/`creationTime`/`updateTime` are microseconds	See Cookbook: session portability for the full recipe.
Sessions die after migrating cookies from another browser	The identity didn't match the session's origin device — "impossible login" → anti-fraud revokes ALL sessions (observed on LinkedIn)	Always write `identity.toml` to match the origin device (platform, timezone, locale, screen, cores, GPU). AGENTS.md §8 has the full protocol.
Typing into an editor works but the site ignores the change	The editor framework listens for trusted events only	≥ 0.8.1 types via real key events; for older versions use the site's own editor-native input paths (AGENTS.md §3).

Symptom	Cause	Fix
`Read-only file system` building the runtime in a container	Cargo needs to write `target/`	Don't mount the source tree read-only for builds.
Docker image build: `release is missing engine or ghostcloak-mcp assets`	The engine build takes ~2h to attach zips after a release	The image workflow waits for assets automatically; if building by hand, check the release page first.
`cargo build` finishes in 0.2s without compiling your changes	Concurrent builds sharing the target dir can confuse incremental state	`touch` the edited files or `cargo clean -p <crate>`.

Don't see your failure here? Open a Discussion — solutions that get confirmed end up on this page.