Building with autodoc and --jobs auto fails when importing from "asyncio

[ypnos]

Describe the bug

I have code that includes an import to asyncio. Both these imports trigger the problem:

import asyncio

from asyncio import Queue

When running build with "--jobs auto", the error is produced:

Process ForkProcess-10:%] my_device2.engine
Traceback (most recent call last):
  File "/usr/lib/python3.12/multiprocessing/process.py", line 314, in _bootstrap
    self.run()
  File "/usr/lib/python3.12/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/home/jordajo/projects/pya/pyappspace/.venv/lib/python3.12/site-packages/sphinx/util/parallel.py", line 90, in _process
    pipe.send((failed, collector.logs, ret))
  File "/usr/lib/python3.12/multiprocessing/connection.py", line 206, in send
    self._send_bytes(_ForkingPickler.dumps(obj))
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/multiprocessing/reduction.py", line 51, in dumps
    cls(buf, protocol).dump(obj)
_pickle.PicklingError: Can't pickle <class 'asyncio.current_task.get_name'>: import of module 'asyncio.current_task' failed

(This leads to EOFError further down the line)

When running with "--jobs 1", the error does not happen.

How to Reproduce

Input file my_device2/engine.py:

import asyncio

Environment Information

Platform:              linux; (Linux-6.18.8-locietta-WSL2-xanmod1-x86_64-with-glibc2.39)
Python version:        3.12.3 (main, Nov  6 2025, 13:44:16) [GCC 13.3.0])
Python implementation: CPython
Sphinx version:        9.1.0
Docutils version:      0.22.4
Jinja2 version:        3.1.6
Pygments version:      2.20.0

Sphinx extensions

["sphinx.ext.autodoc"]

Additional context

No response

[gastmaier]

that's not a sphinx issue, it's your custom extension creating objects that can't be serialized. Sphinx pickles the build environment for each worker and merges them at the end, so anything stored in the environment must be picklable. With a single process there no merge step so it does not need to pickle.
Consider refactoring you code (suspicious asynchronous usage) or at least delete the objects that cannot be serialized after usage