microsoft/aspire · error · InvalidOperationException

Unknown browser protocol error.

Error message

Unknown browser protocol error.

What it means

Thrown by ThrowIfProtocolError when the CDP error payload carries an empty or whitespace-only message and no usable integer code. Rather than throwing a messageless exception, the library substitutes the placeholder text 'Unknown browser protocol error.' It signals the browser reported a failure but provided no diagnostic detail.

Solutions

1. Correlate the error with the CDP command that was in flight via logs
2. Check whether the browser process exited or the DevTools connection dropped
3. Retry the operation on a freshly created target/session
4. Capture raw CDP traffic (verbose logging) to recover the missing error detail

Example fix

// before: swallowing the failure at the call site
try { ParseCommandAckResponse(ack); } catch { /* ignore */ }
// after: log the in-flight method for diagnosis
try { ParseCommandAckResponse(ack); }
catch (InvalidOperationException ex) { logger.LogWarning(ex, "CDP command {Method} failed", method); throw; }

// Check the browser process/DevTools endpoint before sending commands:
var health = await httpClient.GetAsync(devToolsUrl + "/json/version", ct);
health.EnsureSuccessStatusCode();

try { ParseCommandAckResponse(ack); }
catch (InvalidOperationException ex) when (ex.Message == "Unknown browser protocol error.")
{
    logger.LogWarning(ex, "CDP returned an error with no message");
    throw; // rethrow after logging context
}

When it happens

Trigger: Any of the parse methods (ParseCreateTargetResponse, ParseAttachToTargetResponse, ParseGetTargetsResponse, ParseCommandAckResponse, ParseCaptureScreenshotResponse) encountering a CDP error object whose Message property is null/empty and whose Code is not an int.

Common situations: Non-Chromium or embedded browsers returning minimal error payloads; protocol proxies stripping error details; obscure CDP failures like browser shutdown without a message.

Related errors

• (CDP error ).
• Browser debug connection closed by the remote endpoint with…
• Timed out waiting for a tracked browser protocol response to
• Tracked browser host does not expose a WebSocket debug…
• Tracked browser protocol event method was not a string.

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

Appendix: source

Thrown at src/Aspire.Hosting.Browsers/BrowserLogsCdpProtocol.cs:322

    }

    private static void ThrowIfProtocolError(BrowserLogsCdpProtocolError? error)
    {
        if (error is null)
        {
            return;
        }

        var message = string.IsNullOrWhiteSpace(error.Message)
            ? "Unknown browser protocol error."
            : error.Message;

        if (error.Code is int code)
        {
            throw new InvalidOperationException($"{message} (CDP error {code}).");
        }

        throw new InvalidOperationException(message);
    }
}

internal readonly record struct BrowserLogsCdpProtocolMessageHeader(long? Id, string? Method, string? SessionId);

internal abstract record BrowserLogsCdpProtocolEvent(string Method, string? SessionId);

internal sealed record BrowserLogsConsoleApiCalledEvent(string? SessionId, BrowserLogsRuntimeConsoleApiCalledParameters Parameters)
    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.RuntimeConsoleApiCalledMethod, SessionId);

internal sealed record BrowserLogsExceptionThrownEvent(string? SessionId, BrowserLogsExceptionThrownParameters Parameters)
    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.RuntimeExceptionThrownMethod, SessionId);

internal sealed record BrowserLogsLoadingFailedEvent(string? SessionId, BrowserLogsLoadingFailedParameters Parameters)
    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.NetworkLoadingFailedMethod, SessionId);

internal sealed record BrowserLogsLoadingFinishedEvent(string? SessionId, BrowserLogsLoadingFinishedParameters Parameters)
    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.NetworkLoadingFinishedMethod, SessionId);

View on GitHub (pinned to 25830f84bd)