HTML, EML, and MSG format troubleshooting

This guide helps you troubleshoot issues when converting or rendering HTML, EML, or MSG files.

These formats all share a common requirement: They depend on a web browser to process and render content correctly. This browser must be Chromium-based. Misconfigurations or missing browser dependencies are the most common source of issues with these formats.

We assume you’re using the latest version of GdPicture.NET and a supported Chromium-based browser. If you aren’t, update first and verify that the issue persists.

Error identification and solutions

Below are the most common errors and how to resolve them.

UnsupportedFormat — Browser not detected

The UnsupportedFormat error typically means GdPicture cannot detect a valid web browser on your system.

How to solve

Use the IsWebBrowserAvailable method to verify whether a browser is available and properly detected before attempting a conversion.

• Set the browser path manually: If you’re managing your own Chrome Headless Shell installation, you can point GdPicture to it directly.

GdPictureDocumentUtilities.SetWebBrowserPath("<path to chrome headless shell executable>");
using (GdPictureDocumentConverter oConverter = new())
{
    // Your conversion code here.
}

Additionally, we recommend using FetchLatestChromeHeadlessShell to automatically download and configure a compatible headless browser — see the section below for details.

GenericError and OperationTimedOut — Communication issues

The GenericError and OperationTimedOut errors indicate that the browser and GdPicture are having trouble communicating due to configuration or processing issues.

How to solve

• Fetch the latest Chrome Headless Shell (recommended): Use FetchLatestChromeHeadlessShell to automatically download and configure a compatible headless browser.

var latestChromeDownloadPath = GdPictureDocumentUtilities.FetchLatestChromeHeadlessShell(Environment.CurrentDirectory);
GdPictureDocumentUtilities.SetWebBrowserPath(latestChromeDownloadPath);
using (GdPictureDocumentConverter oConverter = new())
{
    // Your conversion code here.
}

• Enable detailed error output: Set the NATIVE_SDK_THROW_On_error environment variable to true to get detailed exceptions instead of generic error codes. This gives you significantly more context about what’s failing. This is highly recommended before reaching out to support.

Environment-specific guidance

Some environments require additional configuration to run Chrome correctly.

Docker environments

When running inside a Docker container, use the following flag to disable the sandbox, which is required in containerized environments:

docker exec my_container google-chrome --headless --no-sandbox --disable-gpu

The --no-sandbox flag is specifically required for Docker environments where Chrome cannot run under a sandboxed user.

Managing Chrome instance memory and zombie processes: In Docker environments especially, unmanaged Chrome instances can linger as zombie processes and cause memory issues over time. We recommend setting a fixed browser pool size using SetWebBrowserPoolSize. This limits the number of concurrent browser instances and ensures each instance has a defined lifespan, after which GdPicture automatically disposes of it.

GdPictureDocumentUtilities.SetWebBrowserPoolSize(4);

Tune this value based on your workload and available memory. A fixed pool size prevents unbounded resource consumption and keeps your Docker environment stable under sustained load.

Windows Service environments

GdPicture does not support running HTML conversion inside a Windows Service when the service is running under the Local System account. Using FetchLatestChromeHeadlessShell will resolve this by providing a properly isolated browser instance.

Linux environments (including Azure)

The Linux runtime cannot run Chrome or Chrome Headless Shell on its own. Installing browser packages directly into a Linux runtime environment on Azure is possible in theory, but it’s cumbersome and may introduce maintenance overhead over time.

Use Docker whenever possible for Linux-based deployments.

Still having issues?

Before reaching out, ensure you’ve worked through all the steps outlined on this page. When contacting support, including all relevant details upfront is the single most effective way to get your issue resolved quickly. Complete details help us resolve your issue faster.

If you’re still experiencing issues after following the guidance above, reach out to our Support team. Be sure to include:

• The exact error message and, if enabled, the detailed output from NATIVE_SDK_THROW_On_error = true
• Your environment details (OS, runtime, Docker or native, GdPicture version)
• Steps to reproduce the issue
• Any relevant code snippets as text, not screenshots

For a complete overview of what makes a great support request, read our GdPicture support best practices blog post — following its guidance ensures we can get back to you with a resolution as fast as possible.