IronPDF on Linux: Crash, Hang, or Blank PDF (Debugger Attached)

Overview

IronPDF's Chrome renderer (CEF) runs in sandboxed subprocesses that cannot be traced on Linux. Attaching a debugger collides with the way those subprocesses launch, which surfaces as a hang, a blank PDF, or a silent crash. Enabling single-process mode while debugging resolves it. The problem is triggered by an attached debugger and is not specific to any Linux distribution or .NET version.

Environment

OS: Linux (any distribution)
Condition: A debugger is attached to the process

Version Metadata

Version Found: 2026.4.2
Version Resolved: N/A

Cause

IronPDF renders through CEF (Chromium Embedded Framework). By default, CEF runs separate, sandboxed subprocesses for rendering. On Linux, those subprocesses are locked down so they cannot be traced with ptrace, and a process can have only one tracer at a time. When a debugger is attached, it collides with the way Chromium launches its sandboxed child processes, leaving the renderer subprocesses hung — which the application sees as a hang, a blank PDF, or a silent crash.

Solution

Recommended — Enable single-process mode. Set the following during application startup, before your first IronPDF operation:

IronPdf.Installation.SingleProcess = true;
Keep this setting out of production. Single-process mode disables CEF's process isolation and is less stable under load. Remove it, or exclude it from release builds, before deploying:
```
#if DEBUG
IronPdf.Installation.SingleProcess = true;
#endif
```