What causes "An error occurred while accessing the file." in microsoft/semantic-kernel?

Inspect the InnerException for the specific IO error code/message.

microsoft/semantic-kernel · error · IOException

An error occurred while accessing the file.

Error message

An error occurred while accessing the file.

What it means

An IOException re-thrown with a generic wrapper when any IOException occurs during the Puppeteer-Sharp rendering pipeline (temp HTML creation, screenshot write). The original exception is preserved as InnerException, so the cause is a file-access problem rather than rendering logic.

Source

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

        // Create a temporary HTML file with the Mermaid code
        string tempHtmlFile = Path.Combine(Path.GetTempPath(), "mermaid_temp.html");
        try
        {
            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

Inspect the InnerException for the specific IO error code/message.
Ensure write permissions and that the output path is not locked by another process.
Run one render at a time or use unique temp file names to avoid contention.
Free disk space and shorten the output path.

Example fix

// before
catch (IOException ex) { throw new IOException("An error occurred while accessing the file.", ex); }
// after - surface the real path and HResult
catch (IOException ex) { throw new IOException($"IO error writing '{outputFilePath}' (0x{ex.HResult:X}).", ex); }

Defensive patterns

Strategy: try-catch

Validate before calling

string dir = Path.GetDirectoryName(Path.GetFullPath(outputFilePath))!;
if (!HasWriteAccess(dir)) throw new IOException($"No write access to {dir}");
// where HasWriteAccess attempts a temp file create/delete probe

Try / catch

try { await MermaidRenderer.GenerateMermaidImageAsync(code, path); }
catch (IOException ex) { logger.LogError(ex, "IO failure rendering {Path}", path); /* retry with unique temp name or report */ }

Prevention

Use unique temp file names per render to avoid lock contention.
Ensure the output directory is writable.
Keep output paths short to avoid path-length limits.

When it happens

Trigger: IOException during temp file write/read or page.ScreenshotAsync(outputFilePath): file locked, permission denied, disk full, path too long, or a temp HTML cleanup conflict.

Common situations: Antivirus locking temp files; concurrent runs writing the same output path; insufficient permissions on output folder; disk-full or path-length limits on Windows.

Related errors

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