pytest-xdist crashed worker: debugging

TL;DR

xdist workers crash from the same causes as serial runs plus shared-state interference. Run with -p no:xdist to confirm parallelism is the trigger, then bisect to the crashing test.

Error

worker 'gw2' crashed while running test_x

Steps

1. Run without xdist: pytest -p no:xdist. Expected: if it passes, parallelism is the trigger.
2. Run with -n2 and --dist loadfile to change distribution. Expected: narrows whether it is load-related.
3. Bisect: run half the suite with xdist until one file crashes a worker. Expected: the crashing file found.
4. Check that file for segfault causes: native extensions, huge memory, fork-unsafe code. Expected: the killer identified.
5. Fix or mark that file run_in_serial (via plugin) and restore parallelism. Expected: green at full speed.

When to use

• worker crashed with xdist.
• Crashes that vanish without -n.

When not to use

• Slow but stable parallel runs (tuning, not crashes).
• Collection errors (happen before workers).

Tool compatibility

• pytest 7/8; pytest-xdist.

Variant phrasings

xdist worker died

Same event; bisect to the file.

gw0 crashed

The worker-named form.

Why it happens

Workers are separate processes sharing nothing, but the tests may assume shared state (files, ports, DBs), and one bad test kills its worker.

Edge cases

• --dist loadscope keeps classes together; fixes some interference.
• Each worker needs its own DB schema or the tests collide.
• -p no:cacheprovider avoids cache races between workers.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst6UO536gyAmvILiYW3NVhg