microsoft/aspire · error · TimeoutError

Connection timeout

Error message

Connection timeout

What it means

Raised by _connect_pipe on Windows when the generated client retried opening the named pipe (via _PipeSocket) for the full timeout window and every attempt failed with FileNotFoundError. It signals the host's pipe never appeared within the allotted time.

Solutions

1. Increase the connection timeout (timeout_sec) passed to the connect helper.
2. Start the host and wait for its 'listening' signal before connecting.
3. Verify the pipe path comes from the current host run (fresh env var/log output).
4. Check host startup logs for errors that prevented pipe creation.

Example fix

// before
sock = _connect_pipe(pipe_path, timeout_sec=5)

// after
sock = _connect_pipe(pipe_path, timeout_sec=60)

if not os.path.exists(r"\\.\pipe" ):
    log.warning("pipe namespace unavailable; host may not be running")

try:
    sock = _connect_pipe(pipe_path, timeout_sec=60)
except TimeoutError:
    log.error("timed out connecting to %s; is the host running?", pipe_path)
    raise

When it happens

Trigger: Calling the client's connection entry point with a timeout_sec too small for host startup; host failing to create the pipe at all (crashed before listening); wrong pipe path causing every retry to miss.

Common situations: Slow machine or cold-start (container pull, restore) exceeding the default timeout; connecting in a test before the AppHost finishes booting; stale environment variable pointing at an old pipe name.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• CreateFile failed with error
• Pipe not found
• ReadFile failed with error
• WriteFile failed with error
• -32603

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/703771407d34afe7. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs:424

                def close(self) -> None:
                    '''Close the handle.'''
                    if self._handle is not None and self._handle != self.INVALID_HANDLE_VALUE:
                        _kernel32.CloseHandle(self._handle)
                        self._handle = None

            def _connect_pipe(socket_path: str, timeout_sec: float) -> _PipeSocket:
                '''Connect to a named pipe with timeout, retrying until available.'''
                pipe_path = f"\\\\.\\pipe\\{socket_path}"
                _logger.debug("Connecting to: %s", pipe_path)

                start_time = time.time()
                while (time.time() - start_time) < timeout_sec:
                    try:
                        return _PipeSocket(pipe_path)
                    except FileNotFoundError:
                        time.sleep(0.1)
                raise TimeoutError("Connection timeout")

        else:
            # On Unix, use socket.socket directly as the pipe socket type
            _PipeSocket = socket.socket  # type: ignore[misc]

            def _connect_pipe(socket_path: str, timeout_sec: float) -> _PipeSocket:
                '''Connect to a Unix domain socket with timeout.'''
                _logger.debug("Connecting to: %s", socket_path)

                start_time = time.time()
                while (time.time() - start_time) < timeout_sec:
                    try:
                        sock = _PipeSocket(socket.AF_UNIX, socket.SOCK_STREAM)
                        sock.settimeout(timeout_sec)
                        sock.connect(socket_path)
                        sock.settimeout(None)  # Set to blocking mode
                        return sock
                    except FileNotFoundError:

View on GitHub (pinned to 25830f84bd)