pytest-xdist crashed worker: debugging

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

INTERNALERROR means a worker process died, not that a test failed - so stop reading test output and read the crash report. Rerun without xdist to isolate it, find which test the worker died on, and look for unpicklable returns, segfaults from native code, or a conftest that kills the interpreter.

pytest-xdist "INTERNALERROR" crashing CI runs: how to debug the worker failure

Steps

1. Read the crash report at the top of the output, not the tail. INTERNALERROR prints the worker-side traceback first; that traceback names the real exception the worker died with.

   Expected: You have the worker's traceback and the exception type that killed it.

2. Rerun the same suite with -n0. If it passes serially, the crash is xdist-specific: something about the test cannot survive the worker boundary, usually pickling.

   Expected: You know whether the crash needs xdist to happen or is a general crash.

3. If it crashes serially too, bisect to the killing test: run files one at a time, then use --lf or deselection to isolate. The last test before the crash is your suspect.

   Expected: You have the single test or fixture that kills the process.

4. Check the suspect for worker-killers: returning unpicklable objects from tests, C extensions that segfault, os._exit or sys.exit calls, and fixtures that exhaust memory or file descriptors.

   Expected: You find the line or object that cannot cross the worker boundary.

5. Fix the killer: make returned objects picklable, guard the native call, or mark the test to run outside xdist. Rerun the full parallel suite to confirm the INTERNALERROR is gone.

   Expected: The parallel run completes with normal test results and no crash report.

Use this when

• a parallel run aborts with INTERNALERROR instead of results
• CI shows a crash report from an xdist worker
• workers die partway through the suite with no test failure recorded

Not for this skill when

• tests fail normally with FAILED lines (that is not a worker crash)
• the error happens during collection before workers spawn
• the run hangs instead of crashing (that is a deadlock, different skill)

Variant phrasings

• pytest-xdist INTERNALERROR how to debug
• xdist worker crashed CI INTERNALERROR
• pytest INTERNALERROR worker failure which test caused it

Why it happens

xdist runs your tests in separate worker processes and pickles results back to the controller. INTERNALERROR is the controller telling you a worker died unexpectedly - the test never got to report a result because its process is gone. The causes cluster: something the test returned could not be pickled, native code segfaulted, or something called exit inside the worker. Reading it as a test failure sends you hunting in the wrong place; it is a process crash wearing a test runner's clothes.

Edge cases

• Add -v so the output shows which test each worker was running when it died; without it you are guessing.
• Memory exhaustion looks like a silent worker death with no traceback; watch the CI runner's memory graph if the crash report is empty.
• If the crash is flaky, suspect resource exhaustion or a race in test ordering rather than a single bad test.

Provenance

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

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

Thread query: pytest-xdist "INTERNALERROR" crashing CI runs: how to debug the worker failure

TL;DR:

Not specified by the original author.

TL;DR

Run python -m pip install pytest-xdist. The -n flag only exists when the xdist plugin is installed; without it, pytest does not recognize -n auto at all.

ModuleNotFoundError: No module named 'xdist'

Fix it

1. Install the plugin. Run python -m pip install pytest-xdist.

   • Expected: Successfully installed pytest-xdist-... execnet-....

2. Verify. Run pytest --version and confirm xdist appears in the plugins list.

   • Expected: plugins: xdist-3.x.x.

3. Use it. Run pytest -n auto.

   • Expected: tests distribute across workers instead of unrecognized arguments: -n.

When this applies

• pytest -n auto says unrecognized arguments, or something imports xdist directly and fails.
• A fresh environment where you installed pytest but forgot xdist.

When it does not apply

• If -n is accepted but workers crash importing your own modules, that is a PYTHONPATH issue in workers, not a missing xdist.

Tool compatibility

pytest-xdist 3.x with pytest 7/8, Python 3.8+.

Why it happens

Parallel execution is a plugin, not core pytest. The package name is pytest-xdist but the import name is xdist.

Edge cases

• In CI, make sure the test step installs the same requirements file that includes pytest-xdist.

pytest-xdist's PyPI page (https://pypi.org/project/pytest-xdist/) documents pip install pytest-xdist and notes the -n option only exists when the plugin is installed. The package/import name split (pytest-xdist vs xdist) is the standard confusion, and execnet is its documented runtime dependency.