---
title: "HTML, EML, and MSG format troubleshooting"
canonical_url: "https://www.nutrient.io/guides/dotnet/troubleshooting/chrome-issues/"
md_url: "https://www.nutrient.io/guides/dotnet/troubleshooting/chrome-issues.md"
last_updated: "2026-05-21T17:12:02.219Z"
description: "How to effectively fix any bugs in GdPicture related to the Chrome dependency"
---

# 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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPictureDocumentUtilities~IsWebBrowserAvailable.html) 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.

```csharp

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

```

Additionally, we recommend using [`FetchLatestChromeHeadlessShell`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPictureDocumentUtilities~FetchLatestChromeHeadlessShell.html) 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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPictureDocumentUtilities~FetchLatestChromeHeadlessShell.html) to automatically download and configure a compatible headless browser.

```csharp

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:

```bash

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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPictureDocumentUtilities~SetWebBrowserPoolSize.html). This limits the number of concurrent browser instances and ensures each instance has a defined lifespan, after which GdPicture automatically disposes of it.

```csharp

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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14~GdPicture14.GdPictureDocumentUtilities~FetchLatestChromeHeadlessShell.html) 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.

| Environment           | Recommendation                                       |
| --------------------- | ---------------------------------------------------- |
| Linux runtime (Azure) | ⚠️ Supported — but complex to configure and maintain |
| Docker on Linux       | ✅ Recommended — reliable and supported               |

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](https://www.nutrient.io/support/request). 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](https://www.nutrient.io/blog/gdpicture-support-best-practices/) blog post — following its guidance ensures we can get back to you with a resolution as fast as possible.
---

## Related pages

- [Add .NET SDK to your project](/guides/dotnet/troubleshooting/add-reference-to-gdpicture-dll.md)
- [Old vs. new headless modes in Google Chrome](/guides/dotnet/troubleshooting/headless-modes-google-chrome.md)