Technology · PRACTICAL GUIDE
Python 3.14 process pools fail in a sandbox? Test forkserver's Unix socket first
A Python 3.14 pool can fail before it serializes any task. Separate an unwritable temp directory from AF_UNIX policy denial, then choose spawn, one worker or a justified context.
Python 3.14 changed the default start method on supported POSIX systems from fork to forkserver. That safer default creates a separate server and uses a local Unix socket, so a restricted job can fail before a worker imports your module or receives a task.
Do not label every traceback a pickling error or make fork the automatic escape hatch. First identify whether the failure is temporary storage, AF_UNIX creation or bind, path length, import safety, or task serialization; each boundary has a different repair.
1. Locate the failure before the first worker
Record sys.version, platform.platform(), multiprocessing.get_start_method() and the complete traceback. A traceback ending in forkserver.ensure_running, connection.arbitrary_address, tempfile.gettempdir or listener.bind is still in launch plumbing; your function has not started.
Keep three errors separate: no usable temporary directory, AF_UNIX path too long, and PermissionError during socket creation or bind. A later PicklingError, local-function AttributeError or recursive startup belongs to the import and serialization branch.
2. Probe storage and the Unix socket separately
Under the same sandbox and user, create a disposable temp directory and bind an AF_UNIX socket inside it. Close the socket and remove the path. This local probe creates no network listener.
If directory creation fails, fix that boundary or use a patch with the documented fallback. If it succeeds but bind gets EPERM, changing TMPDIR cannot grant socket capability. If both pass, run a one-item forkserver pool and then inspect import and pickling rules.
3. Read the patch-version boundary correctly
The current Python 3.14 manual says forkserver is the default on supported POSIX unless no writable temporary directory exists; starting with 3.14.9, spawn becomes the default in that no-temp case. Earlier 3.14 releases can fail with OSError instead.
That fallback is narrow. A writable directory can coexist with a sandbox policy that denies AF_UNIX. A long generated path is another failure. Preserve the exact exception, patch version and path before selecting a workaround.
4. Choose the narrowest safe response
Application code can use multiprocessing.get_context('spawn') or ProcessPoolExecutor(mp_context=...). Keep callables at module scope, guard process creation with if __name__ == '__main__', and pass picklable data. Libraries should accept a caller-provided context instead of changing the global method.
For a CLI that exposes worker count, one worker is usually the least surprising fallback. If processes are required, ask the environment owner for a narrowly scoped local Unix-socket allowance; do not bypass a deliberate policy with a remote service.
Use fork only after the application proves no unsafe threaded or library state is copied. A successful fork probe establishes capability, not safety.
5. Re-test semantics under spawn
Spawn starts a fresh interpreter. Move nested targets and lambdas to importable module scope, guard the entry point, and recreate per-process resources in an initializer. Locks from one multiprocessing context may not work with another.
Do not pass open database connections, event loops or live clients because fork used to copy them. Pass configuration and identifiers, then open resources inside each worker.
6. Accept the repair with a boundary matrix
Record four results: temp-directory creation, AF_UNIX bind, a one-item forkserver pool and a one-item spawn pool. Run the real tool with one worker and with the chosen supported context; keep exit status and artifact hashes for the same input.
Accept only when the intended branch succeeds, a deliberately invalid target still fails for the expected import or pickling reason, shutdown leaves no socket file, and output matches the one-worker baseline. Capability, safety and result equivalence all need evidence.
