Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Most GeneratePdfFromFiles failures start with one input mistake: the string[] argument contains HTML markup, but this overload expects file names or URLs. Save each HTML string as a readable temporary .html file, pass the absolute paths, and then investigate any external CSS, JavaScript, image, DNS, authentication, or deployment problem reported by wkhtmltopdf.
What the method actually accepts
The commonly used overload has the shape GeneratePdfFromFiles(string[] htmlFiles, string coverHtml, Stream output). Each element in htmlFiles is a location to load: a local HTML file name or a URL. It is not an HTML document held directly in a .NET string.
For example, these are locations:
C:appinputone.html/var/app/input/one.htmlhttps://example.test/document.html
This is markup, not a location:
<html><body>Invoice</body></html>Passing markup where a path or URL is expected can produce a WkHtmlToPdfException, including an exit-code-1 HostNotFoundError. The error does not necessarily mean that the first page’s hostname is wrong; it can also refer to a resource inside the page.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Use the correct input pattern
When you already have HTML files or URLs
Pass absolute, readable paths (or complete URLs), keep the output stream open for the call, and read the stream after generation:
#1 Best Overall
var htmlFiles = new[]
{
@"C:appinputone.html",
@"C:appinputtwo.html"
};
using var output = new MemoryStream();
var converter = new NReco.PdfGenerator.HtmlToPdfConverter();
converter.GeneratePdfFromFiles(htmlFiles, null, output);
byte[] pdfBytes = output.ToArray();Use the identity that runs the application or service when checking read permissions. A path that works in an interactive desktop session can fail under IIS, a Windows service, a container, or a scheduled task.
When your source is HTML strings
Write each string to a uniquely named temporary file, flush and close it, then pass those absolute paths. Choose an encoding deliberately (UTF-8 is normally appropriate), create the directory if necessary, and delete the files only after PDF generation completes.
using System.Text;
using NReco.PdfGenerator;
string firstHtml = "<!doctype html><html><body><h1>First page</h1></body></html>";
string secondHtml = "<!doctype html><html><body><h1>Second page</h1></body></html>";
string tempDirectory = Path.Combine(Path.GetTempPath(), "pdf-inputs", Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(tempDirectory);
string firstPath = Path.Combine(tempDirectory, "one.html");
string secondPath = Path.Combine(tempDirectory, "two.html");
try
{
await File.WriteAllTextAsync(firstPath, firstHtml, new UTF8Encoding(false));
await File.WriteAllTextAsync(secondPath, secondHtml, new UTF8Encoding(false));
var converter = new HtmlToPdfConverter();
using var output = new MemoryStream();
converter.GeneratePdfFromFiles(new[] { firstPath, secondPath }, null, output);
byte[] pdfBytes = output.ToArray();
await File.WriteAllBytesAsync("combined.pdf", pdfBytes);
}
finally
{
if (Directory.Exists(tempDirectory))
Directory.Delete(tempDirectory, recursive: true);
}The sample is a pattern, not a guarantee that every application should use the system temporary directory. In production, account for concurrent requests, cleanup after crashes, maximum input size, and permissions. If a failure occurs before cleanup, schedule a separate retention job rather than allowing temporary files to accumulate.
Read HostNotFoundError in context
NReco identifies network errors such as HostNotFoundError, ContentNotFoundError, and ProtocolUnknownError as common signs that wkhtmltopdf could not load an external JavaScript, CSS, image, or similar resource referenced by the input HTML. Once the array contains valid locations, inspect every document for:
<link>and<script>URLs<img src>and background images- CSS
url(...)references, including fonts - redirects, protocol-relative URLs, and relative paths
Resolve relative references against the actual file or page base. Prefer absolute URLs or absolute local paths when the base could differ between development and production. Test from the same machine, container, or service account that launches wkhtmltopdf—not only from your browser.
Network and authentication checks
- Resolve the hostname from the renderer’s environment and verify the route is reachable.
- Check TLS, proxy, firewall, and outbound-egress rules.
- Confirm that the URL does not require browser cookies, a login session, a client certificate, or an authorization header that wkhtmltopdf is not receiving.
- Verify that the server returns the expected content type and status, rather than a redirect to a login or error page.
- For local resources, check that the process can traverse every parent directory and read the file.
A page can load successfully while one image or stylesheet fails. Capture the complete exception text and correlate it with the URLs in the HTML before changing converter settings.
When it is acceptable to ignore failed media
If an image, stylesheet, or other media is genuinely optional, NReco’s FAQ documents this wkhtmltopdf argument:
Free tools Windows power users keep installed
One-click scans. No signup required.
converter.CustomWkHtmlArgs = " --load-media-error-handling ignore ";This can allow PDF creation while unavailable media is omitted. It does not make an inaccessible resource available, and it is unsafe for documents where branding, signatures, charts, or required legal text might disappear. After enabling it, inspect the resulting PDF and log which inputs were used. NReco notes that behavior can depend on wkhtmltopdf’s handling of a nonzero exit when errors are ignored, so validate the output with the versions actually installed in your deployment.
Choose the matching overload and output
The string[] overload is convenient when every input is simply a file name or URL and one output stream is sufficient. NReco also documents an overload that accepts WkHtmlInput[] and writes to a file path, allowing settings per input. If you need different page options or input-specific configuration, verify that your installed package exposes that overload and use the corresponding input type instead of forcing HTML strings into the file-name API.
Do not diagnose an output-path problem as an input problem. Confirm that the destination directory exists, the process can write there, and the stream or file is not disposed before conversion finishes. For large PDFs, avoid unnecessary ToArray() copies when your application can stream the result directly.
Deployment and package checks
The standard NReco.PdfGenerator NuGet package contains Windows wkhtmltopdf binaries. NReco directs cross-platform deployments to NReco.PdfGenerator.LT. Confirm the package reference, native binary availability, operating system, CPU architecture, and runtime before treating a deployment failure as an HTML-input error.
Package listings identify wkhtmltopdf 0.12.6 in NReco.PdfGenerator 1.2.0 and a netstandard2.0 build in 1.2.1. Those are package-history details, not proof of the version in your application. Record the actual resolved package and native binary versions in diagnostics, especially after a deployment or runtime upgrade.
Rank #4
A practical troubleshooting sequence
- Log each array element. Record whether it is an absolute path or URL; reject values that begin with HTML markup.
- Validate existence and access. For local files, check
File.Existsand permissions under the service identity. For URLs, test DNS and HTTP access from the renderer’s host. - Reduce to one input. Generate a PDF from a minimal local HTML file. If that works, add documents one at a time.
- Remove external references temporarily. A self-contained HTML file distinguishes input handling from resource loading.
- Inspect every resource URL. Fix DNS, routing, authentication, redirects, relative bases, or invalid paths.
- Decide whether missing media is optional. Only then consider
--load-media-error-handling ignore. - Verify package and platform. Check the NReco package, wkhtmltopdf binary, operating system, architecture, and runtime.
- Preserve diagnostics. Keep the full exception, input list, converter arguments, and deployment version with the failed job.
Common symptoms and fixes
| Symptom | Likely cause | Action |
|---|---|---|
HostNotFoundError |
Unresolvable host in the page or an input URL | Test DNS and outbound access from the renderer; correct the URL or network policy. |
ContentNotFoundError |
Missing file, 404 response, or blocked resource | Check absolute paths, HTTP status, permissions, and authentication. |
ProtocolUnknownError |
Malformed or unsupported resource scheme | Use a valid http, https, or local path and remove malformed references. |
HTML text passed in string[] |
Wrong overload contract | Write strings to temporary files or use an API designed to accept HTML content. |
| Works on Windows, fails on Linux | Native binary/package mismatch | Review the standard versus LT package and the deployed wkhtmltopdf binary. |
| PDF succeeds but images are absent | Media is inaccessible or intentionally ignored | Fix the resource access; if optional, use the ignore setting and verify the document. |
Reliability considerations
Make temporary-file names unique, enforce size and time limits, and clean up in a finally block. Avoid sharing one mutable converter instance across concurrent requests unless the installed library documents that it is thread-safe. Warm-up and first-run failures can expose missing native dependencies, so exercise conversion during deployment checks. For repeatable output, pin package versions, keep HTML/CSS assets available at stable locations, and log the exact converter arguments.
Or skip the browser setup
If your broader workflow is collecting screenshots rather than assembling HTML files into a PDF, ScreenshotNeo provides a direct API call. It accepts cookie and consent banners before capture, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn those steps off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation. A one-call example is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is included on every plan. If that fits your use case, create a free ScreenshotNeo account.
Frequently Asked Questions
Does GeneratePdfFromFiles merge arbitrary HTML strings directly?
No. The documented string-array overload treats each value as a file name or URL. Persist HTML strings to readable files first, then pass their absolute paths.
Should I always enable –load-media-error-handling ignore?
No. Use it only when missing media is acceptable. Required content should be made reachable or embedded instead.
Why does a local file still report HostNotFoundError?
A referenced stylesheet, script, image, font, or other resource can have an unresolvable host even when the main HTML file is local.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Which NReco package should a Linux deployment use?
NReco identifies the standard package as containing Windows binaries and directs cross-platform users to NReco.PdfGenerator.LT. Verify the package and runtime versions in your own deployment.
Quick Recap
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.
