microsoft/aspire · error · FileNotFoundError

Pipe not found

Error message

Pipe not found: {pipe_path}

What it means

On Windows the generated Python module connects to the host over a named pipe using CreateFile via ctypes. When CreateFile fails with ERROR_FILE_NOT_FOUND, the pipe wrapper raises FileNotFoundError with the pipe path. It means no server is currently listening on that pipe endpoint.

Solutions

1. Ensure the Aspire host / AppHost is running before creating the client.
2. Retry with backoff on FileNotFoundError — _connect_pipe already retries until timeout_sec; increase the timeout if startup is slow.
3. Verify the pipe path matches what the host exported (env var/log line) — a mismatched path will never be found.
4. Check host logs for a crash during startup.

Example fix

// before
client = RpcClient.connect()  # host not up yet -> FileNotFoundError

// after
client = RpcClient.connect(timeout_sec=30)  # wait longer for host pipe to appear

pipe_path = os.environ.get("ASPIRE_PIPE_PATH")
if not pipe_path:
    raise RuntimeError("ASPIRE_PIPE_PATH not set; host not started?")

try:
    client = RpcClient.connect(pipe_path, timeout_sec=60)
except FileNotFoundError:
    log.error("host pipe %s never appeared", pipe_path)
    raise

When it happens

Trigger: Calling the generated client's connect/API entry point while the Aspire host (pipe server) has not started yet, has exited, or the pipe path passed to _connect_pipe is wrong or stale.

Common situations: Racing the host startup (client starts before AppHost creates the pipe); the host process crashed; running from a different user session (named pipe namespace per-session); connecting with an old pipe name after the app was restarted.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Connection timeout
• CreateFile failed with error
• ReadFile failed with error
• WriteFile failed with error
• Headers too large (limit bytes)

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

Appendix: source

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

                ERROR_IO_PENDING = 997
                ERROR_FILE_NOT_FOUND = 2

                def __init__(self, pipe_path: str) -> None:
                    self._handle: int | None = None
                    handle = _kernel32.CreateFileW(
                        pipe_path,
                        self.GENERIC_READ | self.GENERIC_WRITE,
                        0,  # no sharing
                        None,  # default security
                        self.OPEN_EXISTING,
                        self.FILE_FLAG_OVERLAPPED,  # match server's async mode
                        None  # no template
                    )

                    if handle == self.INVALID_HANDLE_VALUE:
                        error = ctypes.get_last_error()
                        if error == self.ERROR_FILE_NOT_FOUND:
                            raise FileNotFoundError(f"Pipe not found: {pipe_path}")
                        raise OSError(f"CreateFile failed with error {error}")

                    self._handle = handle

                def _create_overlapped_event(self) -> _OVERLAPPED:
                    '''Create an OVERLAPPED structure with an event for async I/O.'''
                    overlapped = _OVERLAPPED()
                    overlapped.hEvent = _kernel32.CreateEventW(None, True, False, None)
                    return overlapped

                def recv(self, n: int) -> bytes:
                    '''Read up to n bytes using overlapped I/O.'''
                    buffer = ctypes.create_string_buffer(n)
                    bytes_read = wintypes.DWORD()
                    overlapped = self._create_overlapped_event()

                    try:
                        success = _kernel32.ReadFile(

View on GitHub (pinned to 25830f84bd)