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

NamedPipeConnector.__init__ raises RuntimeError if the active event loop is not asyncio.ProactorEventLoop. Named pipes are a Windows-only IPC mechanism requiring the proactor event loop, which is the default on Windows but does not exist on Linux or macOS (which use SelectorEventLoop).

Solutions

1. On Linux/macOS use UnixConnector with a Unix domain socket instead
2. On Windows ensure the proactor loop is active: asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
3. Gate by platform before instantiating: if sys.platform == 'win32': ... else use an alternative connector

Example fix

# before (crashes on Linux/macOS)
connector = NamedPipeConnector(path=r'\\.\pipe\mypipe')

# after
import sys
if sys.platform == 'win32':
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
    connector = NamedPipeConnector(path=r'\\.\pipe\mypipe')
else:
    connector = UnixConnector(path='/tmp/mypipe.sock')

import sys, asyncio
if sys.platform != 'win32':
    raise RuntimeError('NamedPipeConnector requires Windows')
if not isinstance(asyncio.get_event_loop(), asyncio.ProactorEventLoop):
    raise RuntimeError('NamedPipeConnector requires ProactorEventLoop')
# safe to instantiate

try:
    connector = NamedPipeConnector(path=pipe_path)
except RuntimeError as e:
    if 'proactor' in str(e).lower():
        logger.error('NamedPipeConnector not supported on this platform/loop')
    raise

When it happens

Trigger: Instantiating NamedPipeConnector on Linux, macOS, or any platform whose event loop is not ProactorEventLoop. Also triggered on Windows if a custom SelectorEventLoop was explicitly installed via WindowsSelectorEventLoopPolicy.

Common situations: Running Windows-only named pipe code on a Linux CI runner; testing npipe-based code on a macOS dev machine; explicitly setting asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) on Windows for compatibility with older libraries.

Related errors

• Named Pipes only available in proactor loop under windows
• Session and connector have to use same event loop
• Cannot connect to unix socket
• Cannot initialize a TLS-in-TLS connection to host
• Connector is closed.

AI-assisted analysis of aio-libs/aiohttp@d041d4d0fd (2026-08-11). Data as JSON: /api/errors/11b7d509991059ba. Report an issue: GitHub.

Appendix: source

Thrown at aiohttp/connector.py:1756

    def __init__(
        self,
        path: str,
        force_close: bool = False,
        keepalive_timeout: _SENTINEL | float | None = sentinel,
        limit: int = 100,
        limit_per_host: int = 0,
    ) -> None:
        super().__init__(
            force_close=force_close,
            keepalive_timeout=keepalive_timeout,
            limit=limit,
            limit_per_host=limit_per_host,
        )
        if not isinstance(
            self._loop,
            asyncio.ProactorEventLoop,  # type: ignore[attr-defined]
        ):
            raise RuntimeError(
                "Named Pipes only available in proactor loop under windows"
            )
        self._path = path

    @property
    def path(self) -> str:
        """Path to the named pipe."""
        return self._path

    async def _create_connection(
        self, req: ClientRequest, traces: list["Trace"], timeout: "ClientTimeout"
    ) -> ResponseHandler:
        try:
            async with ceil_timeout(
                timeout.sock_connect, ceil_threshold=timeout.ceil_threshold
            ):
                _, proto = await self._loop.create_pipe_connection(  # type: ignore[attr-defined]
                    self._factory, self._path

View on GitHub (pinned to d041d4d0fd)