{"record":{"id":"3a1067b9dcddc959","repo":"microsoft/aspire","slug":"tracked-browser-host-does-not-expose-a-websocket-debug","errorCode":null,"errorMessage":"Tracked browser host does not expose a WebSocket debug endpoint.","messagePattern":"Tracked browser host does not expose a WebSocket debug endpoint\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Browsers/BrowserHost.cs","lineNumber":42,"sourceCode":"\n    public BrowserHostIdentity Identity { get; } = identity;\n\n    public BrowserHostOwnership Ownership { get; } = ownership;\n\n    public Uri? DebugEndpoint { get; } = debugEndpoint;\n\n    public abstract int? ProcessId { get; }\n\n    public string BrowserDisplayName { get; } = browserDisplayName;\n\n    public abstract Task Termination { get; }\n\n    public virtual async Task<IBrowserLogsCdpConnection> CreateCdpConnectionAsync(\n        Func<BrowserLogsCdpProtocolEvent, ValueTask> eventHandler,\n        ILogger<BrowserLogsSessionManager> logger,\n        CancellationToken cancellationToken)\n    {\n        var debugEndpoint = DebugEndpoint ?? throw new InvalidOperationException(\"Tracked browser host does not expose a WebSocket debug endpoint.\");\n        return await BrowserLogsCdpConnection.ConnectAsync(debugEndpoint, eventHandler, logger, cancellationToken).ConfigureAwait(false);\n    }\n\n    public Task<IBrowserPageSession> CreatePageSessionAsync(\n        string sessionId,\n        Uri url,\n        BrowserConnectionDiagnosticsLogger connectionDiagnostics,\n        Func<BrowserLogsCdpProtocolEvent, ValueTask> eventHandler,\n        CancellationToken cancellationToken)\n    {\n        return CreatePageSessionCoreAsync(sessionId, url, connectionDiagnostics, eventHandler, cancellationToken);\n    }\n\n    public abstract ValueTask DisposeAsync();\n\n    private async Task<IBrowserPageSession> CreatePageSessionCoreAsync(\n        string sessionId,\n        Uri url,","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Browsers/BrowserHost.cs#L24-L60","documentation":"BrowserHost.CreateCdpConnectionAsync opens a Chrome DevTools Protocol WebSocket connection using the host's DebugEndpoint. This error is thrown when DebugEndpoint is null, meaning the tracked browser host never discovered (or lost) its WebSocket debugger URL, so no CDP connection can be established. It is an upfront invariant check before ConnectAsync.","triggerScenarios":"Calling CreateCdpConnectionAsync (directly or via browser-logs session start) on a BrowserHost whose /json/version discovery failed or returned no webSocketDebuggerUrl, e.g. browser started without remote debugging enabled, discovery raced browser startup, or the browser died between discovery and connection.","commonSituations":"Custom/enterprise browser builds with DevTools debugging disabled; launching a browser binary that ignores the remote-debugging-port flag; startup race where the debugger endpoint is queried before Chromium exposes it; browser process exited immediately after launch.","solutions":["Retry after a short delay: the browser may not have exposed the DevTools WebSocket endpoint yet at connect time.","Verify the browser launch flags include remote debugging (--remote-debugging-port) and the build supports DevTools.","Check the browser process is still alive and healthy; restart the tracked browser if it crashed.","Re-run endpoint discovery (/json/version) to repopulate DebugEndpoint before connecting."],"exampleFix":"// before\nvar conn = await host.CreateCdpConnectionAsync(handler, logger, ct); // may throw when DebugEndpoint null\n\n// after: guard in caller\nif (host.DebugEndpoint is null)\n{\n    await Task.Delay(500, ct);\n    await host.RefreshDiscoveryAsync(ct); // re-probe /json/version\n}\nvar conn = await host.CreateCdpConnectionAsync(handler, logger, ct);","handlingStrategy":"retry","validationCode":"if (host.DebugEndpoint is null)\n    throw new InvalidOperationException(\"Browser debug endpoint not discovered yet; wait or re-probe before connecting.\");","typeGuard":"var ready = host is { DebugEndpoint: not null };","tryCatchPattern":"try { await host.CreateCdpConnectionAsync(handler, logger, ct); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"WebSocket debug endpoint\"))\n{ logger.LogWarning(ex, \"No CDP debug endpoint; re-probing /json/version and retrying\"); /* re-discover then retry */ }","preventionTips":["Wait for the browser to expose /json/version before opening CDP connections.","Confirm the browser binary supports DevTools remote debugging flags.","Check the browser process health before connecting."],"tags":["browser","cdp","websocket","browser-logs"],"backgroundTag":"internal-invariant-violation","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"}