microsoft/aspire · error · InvalidOperationException

(CDP error ).

Error message

{message} (CDP error {code}).

What it means

This error is thrown by ThrowIfProtocolError when a Chrome DevTools Protocol (CDP) response contains an error payload. The library surfaces the browser's own error message, appending the numeric CDP error code when one is present. It converts a low-level protocol failure into a standard InvalidOperationException for the calling parse method.

Solutions

1. Inspect the embedded CDP error code and message to identify the failing browser operation
2. Verify the browser instance is still running and the target/session id is valid
3. Re-create the target/session (CreateTarget + AttachToTarget) before retrying the command
4. Upgrade the browser if the method is not supported by its CDP version

Example fix

// before: reusing a captured sessionId after tab close
var targets = ParseGetTargetsResponse(response);
ParseAttachToTargetResponse(AttachToTarget(staleSessionId));
// after: resolve fresh targets and re-attach
var targets = ParseGetTargetsResponse(SendCommand("Target.getTargets"));
var sessionId = ParseAttachToTargetResponse(SendCommand("Target.attachToTarget", ...));

// Before issuing the CDP command, confirm the target/session is alive:
var targets = ParseGetTargetsResponse(SendCommand("Target.getTargets"));
bool targetAlive = targets.Any(t => t.TargetId == targetId);

try { ParseAttachToTargetResponse(SendCommand(cmd)); }
catch (InvalidOperationException ex)
{
    logger.LogWarning(ex, "CDP command failed");
    // re-create target/session and retry once
}

When it happens

Trigger: Calling ParseCreateTargetResponse, ParseAttachToTargetResponse, ParseGetTargetsResponse, ParseCommandAckResponse, or ParseCaptureScreenshotAsync paths when the browser replies to a CDP command with an error object that has a Message and an integer Code (e.g. target closed, unknown session, method not found).

Common situations: Browser crashed or navigated away mid-session; CDP WebSocket connected to the wrong target; a stale sessionId was reused after the tab was closed; sending a CDP method unsupported by the browser version.

Related errors

• Unknown browser protocol 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/354352856adb8dc9. Report an issue: GitHub.

Appendix: source

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

    {
        return JsonSerializer.Deserialize(framePayload, jsonTypeInfo)
            ?? throw new InvalidOperationException("Tracked browser protocol frame was empty.");
    }

    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);

View on GitHub (pinned to 25830f84bd)