microsoft/semantic-kernel · error · InvalidOperationException

An unexpected error occurred during the Mermaid diagram rend

Error message

An unexpected error occurred during the Mermaid diagram rendering.

What it means

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.

Source

Thrown at dotnet/samples/GettingStartedWithProcesses/Utilities/MermaidRenderer.cs:109

        {
            await File.WriteAllTextAsync(tempHtmlFile, htmlContent);

            // Launch Puppeteer-Sharp with a headless browser to render the Mermaid diagram
            using (var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true }))
            using (var page = await browser.NewPageAsync())
            {
                await page.GoToAsync($"file://{tempHtmlFile}");
                await page.WaitForSelectorAsync(".mermaid"); // Wait for Mermaid to render
                await page.ScreenshotAsync(outputFilePath, new ScreenshotOptions { FullPage = true });
            }
        }
        catch (IOException ex)
        {
            throw new IOException("An error occurred while accessing the file.", ex);
        }
        catch (Exception ex) // Catch any other exceptions that might occur  
        {
            throw new InvalidOperationException(
                "An unexpected error occurred during the Mermaid diagram rendering.", ex);
        }
        finally
        {
            // Clean up the temporary HTML file  
            if (File.Exists(tempHtmlFile))
            {
                File.Delete(tempHtmlFile);
            }
        }

        return outputFilePath;
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read InnerException for the specific Puppeteer/Chrome error.
2. Ensure Chromium is downloaded (BrowserFetcher.DownloadAsync completed) and OS dependencies are present (e.g. libxss1).
3. Validate the mermaidCode renders a '.mermaid' element before screenshotting.
4. Run with Headless=false or increased timeouts to diagnose selector/navigation failures.

Example fix

// before
catch (Exception ex) { throw new InvalidOperationException("An unexpected error occurred during the Mermaid diagram rendering.", ex); }
// after - propagate inner type for actionable errors
catch (Exception ex) when (ex is not IOException) { throw new InvalidOperationException($"Mermaid render failed: {ex.Message}", ex); }

await browserFetcher.DownloadAsync(); // ensure Chromium present first
if (string.IsNullOrWhiteSpace(mermaidCode)) throw new ArgumentException("Empty mermaid code.");

try { await MermaidRenderer.GenerateMermaidImageAsync(code, path); }
catch (InvalidOperationException ex) { logger.LogError(ex.InnerException, "Mermaid render failed"); /* inspect Puppeteer error, install deps, or fix mermaid code */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• An error occurred while accessing the file.
• The filename must have a .png extension.
• Could not determine the directory path.
• The directory '{directoryPath}' does not exist.
• Could not determine the assembly path.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/5aecf371b958d69c. Report an issue: GitHub.