{"record":{"id":"5aecf371b958d69c","repo":"microsoft/semantic-kernel","slug":"an-unexpected-error-occurred-during-the-mermaid-di","errorCode":null,"errorMessage":"An unexpected error occurred during the Mermaid diagram rendering.","messagePattern":"An unexpected error occurred during the Mermaid diagram rendering\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/samples/GettingStartedWithProcesses/Utilities/MermaidRenderer.cs","lineNumber":109,"sourceCode":"        {\n            await File.WriteAllTextAsync(tempHtmlFile, htmlContent);\n\n            // Launch Puppeteer-Sharp with a headless browser to render the Mermaid diagram\n            using (var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true }))\n            using (var page = await browser.NewPageAsync())\n            {\n                await page.GoToAsync($\"file://{tempHtmlFile}\");\n                await page.WaitForSelectorAsync(\".mermaid\"); // Wait for Mermaid to render\n                await page.ScreenshotAsync(outputFilePath, new ScreenshotOptions { FullPage = true });\n            }\n        }\n        catch (IOException ex)\n        {\n            throw new IOException(\"An error occurred while accessing the file.\", ex);\n        }\n        catch (Exception ex) // Catch any other exceptions that might occur  \n        {\n            throw new InvalidOperationException(\n                \"An unexpected error occurred during the Mermaid diagram rendering.\", ex);\n        }\n        finally\n        {\n            // Clean up the temporary HTML file  \n            if (File.Exists(tempHtmlFile))\n            {\n                File.Delete(tempHtmlFile);\n            }\n        }\n\n        return outputFilePath;\n    }\n}\n","sourceCodeStart":91,"sourceCodeEnd":124,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/samples/GettingStartedWithProcesses/Utilities/MermaidRenderer.cs#L91-L124","documentation":"A catch-all InvalidOperationException wrapping any non-IO exception thrown during Mermaid rendering (Puppeteer launch, navigation, selector wait, screenshot). The InnerException carries the real failure; the wrapper exists to give a single, predictable exception type for unexpected rendering errors.","triggerScenarios":"Any exception other than IOException inside the try block: Chromium not downloaded/launch failure, navigation timeout to the temp HTML file, '.mermaid' selector never appearing, or Puppeteer-Sharp runtime error.","commonSituations":"Chromium not installed (BrowserFetcher failed), sandbox/dependency issues on Linux containers, malformed mermaid code that never renders the .mermaid element, network/proxy blocking headless browser.","solutions":["Read InnerException for the specific Puppeteer/Chrome error.","Ensure Chromium is downloaded (BrowserFetcher.DownloadAsync completed) and OS dependencies are present (e.g. libxss1).","Validate the mermaidCode renders a '.mermaid' element before screenshotting.","Run with Headless=false or increased timeouts to diagnose selector/navigation failures."],"exampleFix":"// before\ncatch (Exception ex) { throw new InvalidOperationException(\"An unexpected error occurred during the Mermaid diagram rendering.\", ex); }\n// after - propagate inner type for actionable errors\ncatch (Exception ex) when (ex is not IOException) { throw new InvalidOperationException($\"Mermaid render failed: {ex.Message}\", ex); }","handlingStrategy":"try-catch","validationCode":"await browserFetcher.DownloadAsync(); // ensure Chromium present first\nif (string.IsNullOrWhiteSpace(mermaidCode)) throw new ArgumentException(\"Empty mermaid code.\");","typeGuard":null,"tryCatchPattern":"try { await MermaidRenderer.GenerateMermaidImageAsync(code, path); }\ncatch (InvalidOperationException ex) { logger.LogError(ex.InnerException, \"Mermaid render failed\"); /* inspect Puppeteer error, install deps, or fix mermaid code */ }","preventionTips":["Pre-download Chromium and verify OS dependencies in container images.","Validate mermaid code renders a '.mermaid' element before screenshotting.","Increase navigation/selector timeouts for slow environments."],"tags":["mermaid","puppeteer","chromium","rendering"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}