How to Fix the NReco HtmlToPdfConverter Executable OS Platform Error

The NReco HtmlToPdfConverter “executable OS platform” failure usually means that the application is trying to launch a wkhtmltopdf binary that does not match the deployed operating system, executable name, file location, or host permissions. It is not a single, uniquely defined NReco error. Work through these checks in order: identify the OS and architecture of the deployed process, use the correct NReco package, deploy a compatible binary, set its real name and directory, confirm that the host allows child processes, and enable converter logging.

What the error actually tells you

NReco.PdfGenerator starts wkhtmltopdf as a separate operating-system process. Your .NET code can compile successfully while deployment still fails because the process cannot be found, cannot execute on that platform, or is blocked by the hosting plan. A Windows development machine therefore does not prove that the same files will run in Linux, macOS, Docker, or a restricted cloud service.

#	Preview	Product	Price
1		PDF Explained: The ISO Standard for Document Exchange	$14.41	Buy on Amazon
2		Adobe Acrobat 6 PDF For Dummies	$13.00	Buy on Amazon
3		Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware...	$13.39	Buy on Amazon

Use the exact exception and the converter log to distinguish an OS/package problem from a later HTML, network, or rendering error. If the process starts and then reports a page-load or conversion message, investigate that later message separately.

1. Record the deployed runtime, not your workstation

Run these checks inside the environment where the application fails. Record the operating system, CPU architecture, .NET runtime, application identity, and the directory containing the published files.

#1 Best Overall

Sale

PDF Explained: The ISO Standard for Document Exchange

$14.41

Buy on Amazon

dotnet --info
# Linux containers commonly also expose:
uname -a
# Confirm the published files and permissions in the application directory:
ls -la

On Windows, use the published application’s actual process architecture and inspect the deployment directory in File Explorer or PowerShell. The important comparison is the running host versus the binary you copied, not the operating system used to build the project.

• Windows: NReco documents the standard modern-.NET NReco.PdfGenerator package for Windows deployments.
• Linux, macOS, and Docker: NReco documents NReco.PdfGenerator.LT for these cross-platform deployments. The C# API is the same, but the package does not include the wkhtmltopdf binaries; you deploy a compatible binary yourself.
• Architecture: the executable must match the operating-system and CPU architecture of the process. A file copied from another platform is not made compatible by renaming it.

2. Select the package that matches the target OS

Do not solve a cross-platform deployment by adding a Windows-only package to a Linux image. Replace the package with the LT variant and deliberately supply the binary intended for that image.

3. Deploy and configure the real executable

In an LT deployment, compare three things character-for-character: the file that exists, the name configured in NReco, and the directory configured in NReco. NReco’s default executable name is wkhtmltopdf.exe, which is appropriate for Windows but not normally the name used on Linux or macOS.

Use the platform’s actual name

For Linux or macOS, NReco’s example uses wkhtmltopdf. For Windows, the usual name is wkhtmltopdf.exe. If your package or deployment uses a different filename, configure that filename rather than assuming the default.

Point to the directory that contains it

PdfToolPath is the folder where the tool is located. NReco documents the application assemblies directory as the default and can expand tool files from DLL resources when they are absent in supported standard-package scenarios. In LT, treat the path as an explicit deployment setting and make it absolute or resolve it from the application’s known base directory.

using NReco.PdfGenerator;

var converter = new HtmlToPdfConverter
{
    // Windows default is wkhtmltopdf.exe; use wkhtmltopdf on Linux/macOS.
    WkHtmlToPdfExeName = OperatingSystem.IsWindows()
        ? "wkhtmltopdf.exe"
        : "wkhtmltopdf",

    // Set this to the directory that actually contains the binary.
    PdfToolPath = Path.Combine(AppContext.BaseDirectory, "tools")
};

var pdfBytes = converter.GeneratePdf("<html><body>Hello</body></html>");
await File.WriteAllBytesAsync("output.pdf", pdfBytes);

The exact property types can vary with the NReco package version, so compile against the version installed by your project. The diagnostic principle is constant: WkHtmlToPdfExeName must match the deployed filename and PdfToolPath must resolve to its containing directory.

Check execute permission and architecture

On Unix-like systems, verify that the service account can execute the file, not merely read it. A binary copied into a container can lose its execute bit. Also check that a macOS binary is not being used in Linux, or that an x64 binary is not being launched by an incompatible architecture. These failures can appear as a generic process or platform error before any HTML is processed.

4. Confirm the hosting environment permits child processes

NReco states that its converter invokes the command-line tool through System.Diagnostics.Process. The application therefore needs permission to install or access an executable and to launch a child process under its runtime identity. No path correction can fix a host that blocks process creation.

Rank #2

Sale

Adobe Acrobat 6 PDF For Dummies

• Used Book in Good Condition

$13.00

Buy on Amazon

• Some shared ASP.NET hosting environments prohibit executable files or child processes.
• NReco lists UWP/universal applications and mobile apps among environments where the component cannot be used when the executable cannot be installed and launched.
• NReco documents VM-based Windows Azure plans as supported with a path adjustment to the temporary directory, while the shared Azure Apps plan is documented as unsupported. Treat those as product guidance examples and verify the current rules for your exact host and plan.

Ask the hosting provider whether the application identity may call System.Diagnostics.Process, execute files from the deployed directory, and write to the temporary or working directory. If the answer is no, switching from wkhtmltopdf.exe to wkhtmltopdf will not help; move the conversion to a permitted worker or choose a PDF architecture that does not require a local child process.

5. Turn on NReco diagnostics

NReco suppresses wkhtmltopdf’s informational and debug output when Quiet is enabled. Disable it while reproducing the failure and subscribe to LogReceived. The event receives lines emitted by the WkHtmlToPdf process, which can reveal a missing library, denied permission, invalid argument, or a page-load failure.

using NReco.PdfGenerator;

var htmlToPdf = new HtmlToPdfConverter
{
    Quiet = false,
    WkHtmlToPdfExeName = OperatingSystem.IsWindows()
        ? "wkhtmltopdf.exe"
        : "wkhtmltopdf",
    PdfToolPath = Path.Combine(AppContext.BaseDirectory, "tools")
};

htmlToPdf.LogReceived += (sender, e) =>
{
    Console.WriteLine($"WkHtmlToPdf Log: {e.Data}");
};

var bytes = htmlToPdf.GeneratePdf("<h1>Diagnostic test</h1>");
File.WriteAllBytes("diagnostic.pdf", bytes);

Restore Quiet to its normal production setting only after you have captured enough information. Keep the logged executable path, account, and first failing message with the deployment details; those three items usually identify whether the fault is packaging, configuration, or hosting.

6. Apply the result of the checks

The app is Linux, macOS, or Docker but references the standard package

Change the project reference to NReco.PdfGenerator.LT, deploy the binary built for the target image or operating system, set WkHtmlToPdfExeName and PdfToolPath, and rebuild the published artifact. Verify permissions inside the final container or server, not only in the source tree.

The LT package is already installed

List the deployed directory and compare its filename with WkHtmlToPdfExeName. Then verify that PdfToolPath resolves to that directory at runtime. A relative path that worked from an interactive shell may resolve elsewhere when the application runs as a service.

The file exists but the process never starts

Check execute permission, architecture, missing platform libraries, and the host’s child-process policy. Run the binary as the same service account where the host permits it, or have the provider confirm the restriction. If process creation is blocked, redesign the deployment rather than changing only NReco settings.

The process starts and logs a rendering or network error

The OS-platform mismatch is no longer the primary problem. Use the emitted wkhtmltopdf message to investigate URL reachability, HTML validity, TLS, missing assets, or page-specific rendering behavior. The executable troubleshooting path ends once the process launches reliably.

Deployment checklist

• Runtime OS and architecture were recorded from the failing deployment.
• The package matches the target: standard package for documented Windows use, LT for Linux, macOS, and Docker.
• A binary compatible with that target is present in the published artifact or image.
• WkHtmlToPdfExeName exactly matches the file name.
• PdfToolPath resolves to the containing directory at runtime.
• The service identity can read and execute the binary and write required temporary output.
• The host allows System.Diagnostics.Process and child-process execution.
• Quiet = false and LogReceived have been used for a controlled reproduction.
• After a successful launch, any remaining error is treated as a conversion or page problem rather than an OS-platform problem.

Performance, reliability, and cost considerations

NReco’s separate-process design means each conversion depends on process startup, available CPU and memory, filesystem access, and the host’s process limits. Keep the binary in a stable, local path rather than downloading it during every request. In containers, bake the verified binary and permissions into the image so a restart does not produce a different tool.

Rank #3

Sale

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

• Used Book in Good Condition

$13.39

Buy on Amazon

For reliability, log the resolved executable path and package version at startup, run a small health-check conversion after deployment, and capture converter output only at the level appropriate for your production logs. A successful health check proves launchability, not that every external page will render; test representative HTML separately.

There is no single NReco license or infrastructure price established by the documentation summarized here. Your operational cost depends on the hosting plan, process limits, CPU and memory allocation, and whether you must move conversion to another service when the host blocks child processes.

Or skip the browser setup

If your requirement is a clean webpage capture or PDF of a URL rather than a local NReco HTML-to-PDF process, ScreenshotNeo avoids deploying wkhtmltopdf and configuring a browser runtime. It accepts the consent banner like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; every response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.

One GET request is enough for a screenshot:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the complete parameter and response reference in the ScreenshotNeo documentation. The API also supports PNG, JPEG, WebP, and PDF output, full-page captures with lazy images loaded, CSS-selector element captures, device and viewport settings, retina scale, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification.

Python and Node.js clients use the same endpoint:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account to try it without a card.

Frequently Asked Questions

Will renaming a Linux binary to wkhtmltopdf.exe make it work?

No. The filename must match NReco’s setting, but the executable itself must also be built for the host operating system and architecture.

Can I diagnose this only on my development computer?

No. The failing server, container, or hosting plan determines process permissions, paths, architecture, and available libraries.

What should I send to a hosting provider?

Provide the runtime OS and architecture, resolved PdfToolPath, configured executable name, service identity, and the first lines captured with Quiet = false and LogReceived.

Quick Recap

SaleBestseller No. 1

PDF Explained: The ISO Standard for Document Exchange

$14.41

SaleBestseller No. 2

Adobe Acrobat 6 PDF For Dummies

Used Book in Good Condition

$13.00

SaleBestseller No. 3

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

Used Book in Good Condition

$13.39

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.