What causes "CreateFile failed with error {error}" in microsoft/aspire?

Decode the numeric error code (e.g. 5=ACCESS_DENIED, 231=PIPE_BUSY) to identify the cause.

microsoft/aspire · error · OSError

CreateFile failed with error

Error message

CreateFile failed with error {error}

What it means

Raised when the Win32 CreateFile call used to open the Windows named pipe fails with an error other than ERROR_FILE_NOT_FOUND. It wraps the raw Win32 error code from ctypes.get_last_error(), indicating the pipe exists but could not be opened (access denied, pipe busy, invalid path, etc.).

Solutions

Decode the numeric error code (e.g. 5=ACCESS_DENIED, 231=PIPE_BUSY) to identify the cause.
If ERROR_PIPE_BUSY, retry after a short delay or have the host increase maximum pipe instances.
Fix pipe ACLs / run the client as the same user as the host if access is denied.
Validate the pipe path format (must be \\.\pipe\name).

Defensive patterns

Strategy: try-catch

Try / catch

try:
    sock = _PipeSocket(pipe_path)
except OSError as e:
    code = e.winerror if hasattr(e, 'winerror') else None
    log.error("pipe open failed (win32 code %s): %s", code, e)
    raise

Prevention

Run client and host as the same user to avoid pipe ACL denials.
Validate pipe path format before connecting.
Add retry-with-backoff for transient busy conditions.

When it happens

Trigger: Opening a named pipe where the handle is INVALID_HANDLE_VALUE and GetLastError() is not ERROR_FILE_NOT_FOUND — e.g. ERROR_ACCESS_DENIED (ACLs/different user), ERROR_PIPE_BUSY (all instances in use), or ERROR_INVALID_NAME (malformed pipe path).

Common situations: Pipe created by a different user or elevated process (access denied); client hammering the pipe with no free instances; pipe path containing invalid characters or a typo in the \\.\\pipe\\ prefix.

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

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

Appendix: source

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

                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(
                            self._handle,

View on GitHub (pinned to 25830f84bd)