microsoft/semantic-kernel · warning · ArgumentException

The filename must have a .png extension.

Error message

The filename must have a .png extension.

What it means

Thrown by GenerateMermaidImageAsync when the supplied filenameOrPath does not end with '.png'. The renderer uses Puppeteer-Sharp's screenshot API which writes a PNG, so a non-PNG filename is treated as a programmer error via ArgumentException on the parameter.

Source

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

/// <summary>
/// Renders Mermaid diagrams to images using Puppeteer-Sharp.
/// </summary>
public static class MermaidRenderer
{
    /// <summary>
    /// Generates a Mermaid diagram image from the provided Mermaid code.
    /// </summary>
    /// <param name="mermaidCode"></param>
    /// <param name="filenameOrPath"></param>
    /// <returns></returns>
    /// <exception cref="InvalidOperationException"></exception>
    public static async Task<string> GenerateMermaidImageAsync(string mermaidCode, string filenameOrPath)
    {
        // Ensure the filename has the correct .png extension
        if (!filenameOrPath.EndsWith(".png", StringComparison.OrdinalIgnoreCase))
        {
            throw new ArgumentException("The filename must have a .png extension.", nameof(filenameOrPath));
        }

        string outputFilePath;

        // Check if the user provided an absolute path
        if (Path.IsPathRooted(filenameOrPath))
        {
            // Use the provided absolute path
            outputFilePath = filenameOrPath;

            // Ensure the directory exists
            string directoryPath = Path.GetDirectoryName(outputFilePath)
                ?? throw new InvalidOperationException("Could not determine the directory path.");
            if (!Directory.Exists(directoryPath))
            {
                throw new DirectoryNotFoundException($"The directory '{directoryPath}' does not exist.");
            }
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Append '.png' to the filename before calling.
2. Normalize user-supplied filenames: if (!path.EndsWith(".png")) path += ".png".
3. Document that only PNG output is supported.

Example fix

// before
await MermaidRenderer.GenerateMermaidImageAsync(code, "diagram");
// after
string file = filename.EndsWith(".png", StringComparison.OrdinalIgnoreCase) ? filename : filename + ".png";
await MermaidRenderer.GenerateMermaidImageAsync(code, file);

if (!filename.EndsWith(".png", StringComparison.OrdinalIgnoreCase))
    filename += ".png";
await MermaidRenderer.GenerateMermaidImageAsync(code, filename);

bool IsValidPngPath(string p) => p.EndsWith(".png", StringComparison.OrdinalIgnoreCase);

try { await MermaidRenderer.GenerateMermaidImageAsync(code, EnsurePng(filename)); }
catch (ArgumentException ex) when (ex.ParamName == nameof(filename)) { /* append .png and retry */ }

When it happens

Trigger: Calling MermaidRenderer.GenerateMermaidImageAsync(code, filename) with a filename lacking the .png extension (e.g. 'diagram.jpg', 'out', 'diagram').

Common situations: Caller forgets the extension, builds the filename from user input, or passes a different image format expected to be supported.

Related errors

• Could not determine the directory path.
• The directory '{directoryPath}' does not exist.
• Could not determine the assembly path.
• An error occurred while accessing the file.
• Filepath for process {processStateInfo.Name} does not have .

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