microsoft/aspire · error · Win32Exception

Failed to invoke WaitForSingleObject while starting tracked…

Error message

Failed to invoke WaitForSingleObject while starting tracked browser CDP pipe.

What it means

The launcher waits for the tracked browser process to exit using WaitForSingleObject(INFINITE). If the wait returns anything other than WAIT_OBJECT_0 (e.g. WAIT_FAILED), the launcher throws this Win32Exception-named error. It means the OS-level wait on the process handle failed rather than the process exiting with a bad exit code.

Solutions

Check the inner NativeErrorCode (WAIT_FAILED usually means an invalid handle).
Ensure no other code closes or disposes the browser process handle while the wait is pending.
Retry the launch - usually transient; the tracked browser session will be re-created.
Verify the browser isn't being force-killed by an external watchdog or antivirus.
Update Aspire.Hosting.Browsers in case of known handle-lifecycle fixes.

Defensive patterns

Strategy: retry

Validate before calling

// Before waiting, confirm the process handle is alive
if (processHandle.IsClosed || processHandle.IsInvalid)
    throw new InvalidOperationException("Browser process handle is no longer valid; relaunch required.");

Try / catch

try
{
    var result = await WaitForBrowserAsync(processHandle);
}
catch (Win32Exception ex) when (ex.Message.Contains("WaitForSingleObject"))
{
    logger.LogWarning(ex, "Browser wait failed (Win32 {Code}); relaunching session.", ex.NativeErrorCode);
    await RelaunchTrackedBrowserAsync();
}

Prevention

Never dispose or close the browser process handle while a wait is pending.
Avoid external watchdogs that force-kill the browser during tracked sessions.
Treat wait failures as transient and relaunch the session.

When it happens

Trigger: WaitForWindowsProcessAsync's Task.Run body calls WaitForSingleObject(processHandle.DangerousGetHandle(), INFINITE) and gets a result other than WAIT_OBJECT_0 - usually WAIT_FAILED because the handle was invalid, closed, or already destroyed.

Common situations: Browser process terminated and handle became invalid concurrently; a stale or disposed handle passed in; rare OS failures under handle pressure; external watchdog or antivirus force-killing the browser mid-session.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Browsers/BrowserLogsPipeBrowserProcessLauncher.Windows.cs:222

                builder.Append('\\');
                builder.Append('"');
                continue;
            }

            builder.Append(character);
        }

        builder.Append('"');
    }

    private static async Task<BrowserLogsProcessResult> WaitForWindowsProcessAsync(SafeWaitHandle processHandle)
    {
        return await Task.Run(() =>
        {
            var waitResult = WaitForSingleObject(processHandle.DangerousGetHandle(), INFINITE);
            if (waitResult != WAIT_OBJECT_0)
            {
                throw CreateWindowsException("WaitForSingleObject");
            }

            if (!GetExitCodeProcess(processHandle.DangerousGetHandle(), out var exitCode))
            {
                throw CreateWindowsException("GetExitCodeProcess");
            }

            return new BrowserLogsProcessResult(unchecked((int)exitCode));
        }).ConfigureAwait(false);
    }

    private static Win32Exception CreateWindowsException(string operation) =>
        new(Marshal.GetLastWin32Error(), $"Failed to invoke {operation} while starting tracked browser CDP pipe.");

    private static void CloseWindowsHandle(IntPtr handle)
    {
        if (handle != IntPtr.Zero && !CloseHandle(handle))
        {

View on GitHub (pinned to 25830f84bd)