Crash, Hang, or Blank PDF on Linux with a Debugger Attached
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 = TrueSingle-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
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.
