1. IronPDF
  2. Troubleshooting
  3. System.Environment.FailFast with ReadyToRun

System.Environment.FailFast with ReadyToRun

Curtis Chau
Curtis Chau
Updated:

A .NET application crashes the moment it first touches an IronPDF class, terminating through System.Environment.FailFast at startup or during early initialization. When the app is published with ReadyToRun (R2R) compilation, that ahead-of-time step is usually the cause. You keep ReadyToRun on for the application and exclude IronPdf.dll from it.

The application requested process termination through System.Environment.FailFast. Message: Stack: at System.Environment.FailFast(System.String) at <Module>..cctor() at Program.<Main>$(System.String[])

ReadyToRun compiles assemblies ahead of time to speed up startup. In some environments that ahead-of-time step interferes with libraries that depend on runtime initialization behavior, IronPDF among them. The process can fail very early, often before any IronPDF logging is available, which is why no logs are written before the crash.

This issue shows up only in the deployed environment, typically ASP.NET Core or IIS-hosted apps on Windows (including Windows Server) targeting win-x64. The same machine can behave differently inside IIS than outside it. A confirmed production case ran IronPDF 2026.4.1 on .NET 10, an ASP.NET Core web app under IIS (w3wp.exe), on Windows Server 2025 Datacenter on AWS EC2.

Solution

1. Keep ReadyToRun enabled

There is no need to disable ReadyToRun outright. If your application depends on it, leave the property in place:

<PropertyGroup>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>
<PropertyGroup>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>
XML

2. Exclude IronPdf.dll from ReadyToRun compilation

Add the exclusion to your .csproj:

<ItemGroup>
  <PublishReadyToRunExclude Include="IronPdf.dll" />
</ItemGroup>
<ItemGroup>
  <PublishReadyToRunExclude Include="IronPdf.dll" />
</ItemGroup>
XML

This single line is what restores normal behavior: it leaves the rest of the app R2R-compiled while letting IronPDF initialize at runtime as it expects.

CautionUse the exact syntax shown. Do not wrap the exclusion inside another container block.

3. Full .csproj example

A working project file looks like this:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="IronPdf" Version="2026.4.1" />
</ItemGroup>
<ItemGroup>
  <PublishReadyToRunExclude Include="IronPdf.dll" />
</ItemGroup>
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="IronPdf" Version="2026.4.1" />
</ItemGroup>
<ItemGroup>
  <PublishReadyToRunExclude Include="IronPdf.dll" />
</ItemGroup>
XML

4. Republish and redeploy

With the project file updated, push a fresh build:

  1. Rebuild the application.
  2. Republish it for your intended runtime, such as win-x64.
  3. Redeploy the updated build.
  4. Restart the IIS site or recycle the Application Pool.
  5. Test the same IronPDF code path again.

In the confirmed production case, excluding IronPdf.dll from ReadyToRun compilation cleared the System.Environment.FailFast crash and the app ran normally under IIS.

When to Try This Fix

Reach for this when the symptoms line up:

  • PublishReadyToRun=true: ReadyToRun is enabled on the published app.
  • First call crashes: the failure hits the moment an IronPDF class is touched.
  • Startup timing: the error appears during startup or early static initialization.
  • Deployed Windows host: the app runs under IIS or another deployed Windows environment.

For full guidance, see Using ReadyToRun with IronPDF.

Curtis Chau
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.

...

Read More
Ready to Get Started?
Nuget Downloads 19,680,294 | Version: 2026.7 just released
Still Scrolling Icon

Still Scrolling?

Want proof fast? PM > Install-Package IronPdf
run a sample watch your HTML become a PDF.