Crash, Hang, or Blank PDF on Linux with a Debugger Attached

Updated:July 2, 2026

On Linux, attaching a debugger to your application can leave IronPDF hung, returning a blank PDF, or crashing silently. It happens whenever a debugger is attached, regardless of the Linux distribution or .NET version.

IronPDF renders through CEF (Chromium Embedded Framework), which by default spawns separate, sandboxed subprocesses to handle 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. Attaching a debugger collides with the way Chromium launches its sandboxed child processes, so the renderer subprocesses hang. Your application sees that as a hang, a blank PDF, or a silent crash.

Solution

Recommended: enable single-process mode. Set it during application startup, before your first IronPDF operation:

IronPdf.Installation.SingleProcess = true;

IronPdf.Installation.SingleProcess = true;

IronPdf.Installation.SingleProcess = True

$vbLabelText $csharpLabel

Single-process mode keeps rendering in the main process, so there is no sandboxed child for the debugger to collide with.

Because that setting disables CEF's process isolation and is less stable under load, keep it out of production. Scope it to debug builds so it never ships in a release:

#if DEBUG
IronPdf.Installation.SingleProcess = true;
#endif

#if DEBUG
IronPdf.Installation.SingleProcess = true;
#endif

#If DEBUG Then
    IronPdf.Installation.SingleProcess = True
#End If

$vbLabelText $csharpLabel

WarningSingle-process mode disables CEF's process isolation and is less stable under load. Remove it or exclude it from release builds before deploying.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Ready to Get Started?

Nuget Downloads 19,820,650 | Version: 2026.7 just released