aio-libs/aiohttp · error · RuntimeError

Named Pipes only available in proactor loop under windows

Error message

Named Pipes only available in proactor loop under windows

What it means

NamedPipeSite relies on loop.start_serving_pipe (line 253), which only exists on asyncio's ProactorEventLoop, and proactor loops only exist on Windows. On Linux/macOS or with the default SelectorEventLoop, the constructor raises RuntimeError at line 235-240.

Source

Thrown at aiohttp/web_runner.py:238

        server = self._runner.server
        assert server is not None
        self._server = await loop.create_unix_server(
            server,
            self._path,
            ssl=self._ssl_context,
            backlog=self._backlog,
        )


class NamedPipeSite(BaseSite):
    __slots__ = ("_path",)

    def __init__(self, runner: "BaseRunner[Any]", path: str) -> None:
        loop = asyncio.get_running_loop()
        if not isinstance(
            loop, asyncio.ProactorEventLoop  # type: ignore[attr-defined]
        ):
            raise RuntimeError(
                "Named Pipes only available in proactor loop under windows"
            )
        super().__init__(runner)
        self._path = path

    @property
    def name(self) -> str:
        return self._path

    async def start(self) -> None:
        await super().start()
        loop = asyncio.get_running_loop()
        server = self._runner.server
        assert server is not None
        _server = await loop.start_serving_pipe(  # type: ignore[attr-defined]
            server, self._path
        )
        self._server = _server[0]

View on GitHub (pinned to c0ef574e29)

Solutions

1. On Windows, ensure a ProactorEventLoop (default since Python 3.8) is running: asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy()).
2. On non-Windows, do not use NamedPipeSite — use UnixSite (Unix sockets) or TCPSite.
3. Branch your transport choice by platform (sys.platform == 'win32').

Example fix

# before (on Linux)
site = NamedPipeSite(runner, r'\\.\pipe\foo')  # raises RuntimeError

# after (on Linux, use unix socket)
site = UnixSite(runner, '/tmp/app.sock')

import sys, asyncio

def make_pipe_site(runner, path):
    from aiohttp.web import NamedPipeSite, UnixSite
    if sys.platform != 'win32':
        return UnixSite(runner, path)  # fallback for non-Windows
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
    return NamedPipeSite(runner, path)

import asyncio

def supports_named_pipes() -> bool:
    try:
        return isinstance(asyncio.get_running_loop(), asyncio.ProactorEventLoop)
    except RuntimeError:
        return False

When it happens

Trigger: Constructing `NamedPipeSite(runner, r'\\.\pipe\foo')` on a non-Windows OS, or on Windows while a custom SelectorEventLoop policy is active.

Common situations: Developing on Linux/macOS and using Windows-only NamedPipeSite; setting a SelectorEventLoop policy on Windows; cross-platform code that didn't branch on OS.

Related errors

• Named Pipes only available in proactor loop under windows
• Compress wbits must between 9 and 15, zlib does not support
• 1007
• Session and connector have to use same event loop
• Cannot initialize a TLS-in-TLS connection to host {req.url.h

AI-assisted analysis of aio-libs/aiohttp@c0ef574e29 (2026-08-04). Data as JSON: /data/errors/2aabca94cd51936b.json. Report an issue: GitHub.