{"record":{"id":"b22e18bcbbfa304f","repo":"microsoft/aspire","slug":"unknown-browser-protocol-error","errorCode":null,"errorMessage":"Unknown browser protocol error.","messagePattern":"Unknown browser protocol error\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Browsers/BrowserLogsCdpProtocol.cs","lineNumber":322,"sourceCode":"    }\n\n    private static void ThrowIfProtocolError(BrowserLogsCdpProtocolError? error)\n    {\n        if (error is null)\n        {\n            return;\n        }\n\n        var message = string.IsNullOrWhiteSpace(error.Message)\n            ? \"Unknown browser protocol error.\"\n            : error.Message;\n\n        if (error.Code is int code)\n        {\n            throw new InvalidOperationException($\"{message} (CDP error {code}).\");\n        }\n\n        throw new InvalidOperationException(message);\n    }\n}\n\ninternal readonly record struct BrowserLogsCdpProtocolMessageHeader(long? Id, string? Method, string? SessionId);\n\ninternal abstract record BrowserLogsCdpProtocolEvent(string Method, string? SessionId);\n\ninternal sealed record BrowserLogsConsoleApiCalledEvent(string? SessionId, BrowserLogsRuntimeConsoleApiCalledParameters Parameters)\n    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.RuntimeConsoleApiCalledMethod, SessionId);\n\ninternal sealed record BrowserLogsExceptionThrownEvent(string? SessionId, BrowserLogsExceptionThrownParameters Parameters)\n    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.RuntimeExceptionThrownMethod, SessionId);\n\ninternal sealed record BrowserLogsLoadingFailedEvent(string? SessionId, BrowserLogsLoadingFailedParameters Parameters)\n    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.NetworkLoadingFailedMethod, SessionId);\n\ninternal sealed record BrowserLogsLoadingFinishedEvent(string? SessionId, BrowserLogsLoadingFinishedParameters Parameters)\n    : BrowserLogsCdpProtocolEvent(BrowserLogsCdpProtocol.NetworkLoadingFinishedMethod, SessionId);","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Browsers/BrowserLogsCdpProtocol.cs#L304-L340","documentation":"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.","triggerScenarios":"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.","commonSituations":"Non-Chromium or embedded browsers returning minimal error payloads; protocol proxies stripping error details; obscure CDP failures like browser shutdown without a message.","solutions":["Correlate the error with the CDP command that was in flight via logs","Check whether the browser process exited or the DevTools connection dropped","Retry the operation on a freshly created target/session","Capture raw CDP traffic (verbose logging) to recover the missing error detail"],"exampleFix":"// before: swallowing the failure at the call site\ntry { ParseCommandAckResponse(ack); } catch { /* ignore */ }\n// after: log the in-flight method for diagnosis\ntry { ParseCommandAckResponse(ack); }\ncatch (InvalidOperationException ex) { logger.LogWarning(ex, \"CDP command {Method} failed\", method); throw; }","handlingStrategy":"try-catch","validationCode":"// Check the browser process/DevTools endpoint before sending commands:\nvar health = await httpClient.GetAsync(devToolsUrl + \"/json/version\", ct);\nhealth.EnsureSuccessStatusCode();","typeGuard":null,"tryCatchPattern":"try { ParseCommandAckResponse(ack); }\ncatch (InvalidOperationException ex) when (ex.Message == \"Unknown browser protocol error.\")\n{\n    logger.LogWarning(ex, \"CDP returned an error with no message\");\n    throw; // rethrow after logging context\n}","preventionTips":["Keep verbose CDP logging enabled to recover details absent from the error message","Monitor browser process liveness before and during command execution","Avoid non-Chromium endpoints that emit sparse error payloads"],"tags":["cdp","browser","protocol-error","unknown-error"],"backgroundTag":"api-error-response","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}