How to Fix TuesPechkin Hanging After the First PDF Conversion
Stop TuesPechkin from hanging after its first PDF conversion with the documented converter lifetime pattern, diagnostics, fixes, and deployment guidance.

A TuesPechkin call that converts one PDF successfully and then hangs is usually a converter-lifetime or hosting problem, but the symptom alone does not identify one universal cause. Start with the project’s documented lifetime rule: create the converter once, keep it for the application lifetime, and use the thread-safe converter in multithreaded applications such as IIS.
The most important rules are:
- Use
StandardConverterfor a single-threaded application. - Use
ThreadSafeConverterfor a multithreaded application or IIS. - Keep one converter in a static field or singleton.
- Do not construct a converter for every request.
- Do not create multiple converter or toolset instances inside one process or IIS application pool.
The README states this directly: “Keep the converter somewhere static, or as a singleton instance!” It also says not to run the setup code more than once in the application lifecycle. Treat that as the starting point for every diagnosis.
1. Use the correct converter lifetime
Single-threaded application: StandardConverter
For a console utility or another genuinely single-threaded process, initialize one StandardConverter and reuse it.

using System;
using TuesPechkin;
using TuesPechkin.Definitions;
public static class PdfConverter
{
private static readonly IConverter Converter =
new StandardConverter(new PdfToolset());
public static byte[] Convert(string html)
{
var document = new HtmlToPdfDocument
{
GlobalSettings =
{
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4
},
Objects =
{
new ObjectSettings
{
HtmlText = html,
WebSettings = { DefaultEncoding = "utf-8" }
}
}
};
return Converter.Convert(document);
}
}
class Program
{
static void Main()
{
var pdf = PdfConverter.Convert("<h1>Invoice</h1>");
System.IO.File.WriteAllBytes("invoice.pdf", pdf);
}
}
The static field ensures that repeated calls use the same native converter and toolset. Do not move new StandardConverter(...) into Convert.
Multithreaded or IIS application: ThreadSafeConverter
Web applications can receive simultaneous requests, so use ThreadSafeConverter and still retain exactly one instance for the application lifetime.
using System;
using TuesPechkin;
using TuesPechkin.Definitions;
public static class PdfService
{
private static readonly IConverter Converter =
new ThreadSafeConverter(new PdfToolset());
public static byte[] ConvertHtml(string html)
{
var document = new HtmlToPdfDocument
{
GlobalSettings =
{
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4
},
Objects =
{
new ObjectSettings
{
HtmlText = html,
WebSettings = { DefaultEncoding = "utf-8" }
}
}
};
return Converter.Convert(document);
}
}
Register this service as a singleton if your dependency-injection container supports it. A singleton registration is useful only if every code path resolves that same instance; a second manually constructed converter still violates the one-instance rule.
2. Check for accidental multiple instances
Search the whole solution for new StandardConverter, new ThreadSafeConverter, new PdfToolset, and any factory that creates them. Common causes include:
| Pattern | Why it causes trouble | Fix |
|---|---|---|
| Converter created inside a controller action | Every request loads another native converter. | Move construction to a static field or singleton service. |
| One converter per user session | Sessions multiply native processes and memory use. | Share one application-level converter. |
| Both startup code and a DI factory create converters | The process contains multiple toolsets. | Choose one composition root and register one instance. |
| Separate converter in a health check | The health check violates the same process-wide lifetime rule. | Check the existing service or run the probe out of process. |
| Multiple IIS applications share an application pool | The documented restriction applies to the process/application-pool arrangement. | Keep one instance in each process and avoid duplicate initialization. |
Add a startup log containing the converter type and process ID. If the log appears more than once in one process, initialization is happening repeatedly. Also log application start and stop events so an IIS recycle is not mistaken for a conversion hang.
3. Pick the right hosting arrangement
The converter mode depends on the thread model and hosting environment:
| Environment | Converter | Lifetime |
|---|---|---|
| Single-threaded command-line tool | StandardConverter |
One static or singleton instance |
| ASP.NET, worker service, background queue | ThreadSafeConverter |
One instance per process |
| IIS with the IIS-compatible setup | ThreadSafeConverter and the documented remoting arrangement |
One converter/toolset in the application pool |
Do not “fix” a hang by switching converter classes at random. First identify whether calls can overlap. A console program that never overlaps calls has a different requirement from an IIS site serving concurrent requests.
4. Investigate RemotingToolset carefully
If your IIS setup uses RemotingToolset, inspect its lifetime and shutdown path. A community answer reports that calling RemotingToolset.Unload() resolved that author’s observed hang. That is an anecdotal workaround, not an official or generally verified fix. It can be unsafe if shared state is still being used.
Use unloading only after you understand which component owns the toolset and whether other requests can still be converting. Never unload a shared toolset after every request. If you test the workaround, do it in a controlled deployment and record:
- Whether the call is blocked, throws, or completes only after process termination.
- Whether another request is using the converter.
- CPU and memory before and after unloading.
- Whether the next conversion can start cleanly.
5. Verify versions, architecture, and the input
TuesPechkin was built and tested around wkhtmltopdf 0.12.2. Record the exact TuesPechkin package, wkhtmltopdf version, operating system, process architecture, and deployment method. A related issue describes a larger conversion hanging with an SEHException after a newer wkhtmltopdf installation, but that report does not prove that version drift causes the first-conversion hang.
Compare a minimal document with the failing document:
<!doctype html>
<html>
<head><meta charset="utf-8"></head>
<body><h1>Conversion probe</h1></body>
</html>
Then add one variable at a time:
- Local CSS and images.
- External stylesheets and fonts.
- JavaScript.
- Large tables or long pages.
- Remote resources that require authentication.
Document size is a diagnostic dimension, not a general threshold. The “six or more pages” wording in one issue report is not a universal limit. A larger document can expose resource, memory, or renderer problems, but it does not establish the root cause.
6. Reproduce with wkhtmltopdf directly
Save the same HTML and resources to a test directory and run the matching wkhtmltopdf binary directly where practical. If the direct command also hangs, investigate wkhtmltopdf, its inputs, or the host environment. If direct conversion succeeds while the wrapper hangs, compare process lifetime, arguments, architecture, and toolset setup.
Visual differences alone do not establish a wrapper defect. Capture the exact command, exit code, stderr, elapsed time, and output size. Use a fixed local HTML file first so DNS, TLS, authentication, and remote servers are removed from the experiment.
7. A disciplined diagnostic sequence
- Confirm the symptom. Does the second call block forever, throw an exception, or finish only when the process exits?
- Log the process. Include process ID, thread ID, converter type, and initialization count.
- Inspect construction. Ensure the converter and toolset are created once.
- Match the thread model. Use
ThreadSafeConverterfor overlapping calls and IIS. - Remove duplicates. Check startup code, DI factories, controllers, sessions, health checks, and background jobs.
- Check RemotingToolset. Test lifecycle behavior without unloading shared state during active work.
- Record versions. Include TuesPechkin, wkhtmltopdf, .NET runtime, OS, architecture, and IIS configuration.
- Shrink the input. Reproduce with local, minimal HTML and then add resources incrementally.
- Run the native binary. Compare direct wkhtmltopdf behavior with wrapper behavior.
- Retest after an application recycle. A recycle can hide lifetime bugs, so verify that the second and third conversions work in the same process.
8. Reliability and performance practices
- Queue conversions when traffic can spike, and apply a maximum wait time at the job layer.
- Keep conversion work off request threads when PDFs can be large.
- Bound concurrent jobs according to available CPU and memory; increasing parallelism does not guarantee higher throughput.
- Cache stable PDFs by a content hash when the source is unchanged.
- Record conversion duration, output bytes, exception type, and input identifier.
- Use a process supervisor and health checks that detect a stuck worker without creating a second converter in the same process.
- Pin the native binary and package versions during an investigation so version changes do not confound results.
There is no supported general page-count or file-size limit in the supplied guidance. Establish limits for your own templates by measuring memory, elapsed time, and failure behavior in your deployment.
9. Common errors and fixes
| Observation | Likely area | Action |
|---|---|---|
| First conversion works; second blocks | Repeated construction or incorrect lifetime | Use one static/singleton converter and one toolset. |
| Only IIS hangs | Thread model or remoting arrangement | Use the documented thread-safe IIS setup and inspect application-pool initialization. |
| CPU rises after adding sessions | Per-session converter instances | Remove session-owned instances; share one application-level converter. |
SEHException on larger input |
Native renderer, version, architecture, or workload | Record versions and reproduce with the native binary and a reduced document. |
| Works after process restart only | Native state is not being reused safely | Check duplicate initialization, toolset lifetime, and shutdown behavior. |
| External pages never finish | Network resource or script dependency | Replace remote assets with local fixtures and add resources back one at a time. |
10. Or skip the browser setup
If the job is simply to turn a URL into an image or PDF, ScreenshotNeo provides a hosted capture API and MCP server. It accepts one GET request and returns a clean PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
For a PDF response, use the PDF options documented by ScreenshotNeo while keeping the same endpoint and authentication pattern. The service can also capture a full page, one CSS-selected element, or HTML/CSS supplied for rendering; wait for a selector, delay, or network idle; set custom headers, cookies, user agent, timezone, geolocation, and authorization; block ads, trackers, requests, or resource types; and run custom CSS or JavaScript.
Before capture, ScreenshotNeo accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its 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 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to try it.
11. FAQ
Should I dispose the converter after every PDF?
No. TuesPechkin’s documented guidance is to retain one converter for the application lifecycle. Repeated construction is a primary thing to eliminate when the second conversion hangs.
Is StandardConverter always wrong in a web app?
It is intended for single-threaded use. A web app or IIS site can process overlapping requests, so follow the documented thread-safe arrangement there.
Does RemotingToolset.Unload() permanently solve the problem?
No universal fix is established. One community report says unloading resolved that deployment’s hang, but treat it as a conditional workaround and verify that no shared conversion is active.
Does a newer wkhtmltopdf version cause every hang?
No. TuesPechkin documents testing around wkhtmltopdf 0.12.2, and a separate issue reports a hang with a newer installation. Those facts make version recording important, not conclusive.
What should I collect before opening an issue?
Provide the smallest reproducible HTML, converter type, initialization count, process architecture, OS, .NET and TuesPechkin versions, wkhtmltopdf version, hosting method, exact exception or blocking state, and whether direct wkhtmltopdf reproduces it.


