IronPDF Startup Crash with WEBSITE_RUN_FROM_PACKAGE

Updated:July 9, 2026

IronPDF can crash at startup on Azure App Service and Azure Functions when the app is deployed with WEBSITE_RUN_FROM_PACKAGE = 1. That setting mounts the app root (C:\home\site\wwwroot) as a read-only package filesystem, and IronPDF's startup file system scan fails against it, usually at the first IronPDF call such as setting the license key.

System.IO.FileNotFoundException

The scan is not something IronPDF intentionally requires. It is a side effect of Ninject's default extension auto-loading. Because C:\home\site\wwwroot is read-only under WEBSITE_RUN_FROM_PACKAGE = 1, the scan throws FileNotFoundException and initialization stops before any PDF work runs. This is confirmed as a bug, and a development ticket is logged to address it.

This affects versions 2026.7.0.2, 2025.12.2, and 2025.3.6 on Windows (win-x64) under .NET 10.

Solution

In your Azure App Settings, set the following and then redeploy:

WEBSITE_RUN_FROM_PACKAGE = 0

Deploying from Visual Studio? Uncheck Run from package file (recommended) during the Publish step.

Visual Studio Publish dialog with the Run from package file (recommended) checkbox unchecked

Depending on your deployment pipeline, this setting can be applied from several different places. Track down where it is defined and where it might be overwritten.
To apply the change: you must redeploy. The setting alone has no effect until the app is redeployed.

Native IronPDF Users

If you run native IronPDF (not the remote IronPDF engine), setting WEBSITE_RUN_FROM_PACKAGE = 0 is mandatory regardless of the scan bug above. At startup, IronPDF extracts the native Chrome renderer binaries and runtime libraries to a writable location. A read-only C:\home\site\wwwroot blocks that extraction, so this step stands on its own.

For more background, see the Azure Linux WEBSITE_RUN_FROM_PACKAGE guide.

Workarounds That Don't Work

Moving the first IronPDF call out of startup: the crash still happens on first use from an on-demand endpoint.
Switching between WEBSITE_RUN_FROM_ZIP and WEBSITE_RUN_FROM_PACKAGE: both mount read-only and fail the same way.
Using the remote IronPdfEngine: the startup scan still runs first, so it fails before the remote connection is used.
Setting Installation.TempFolderPath to a writable path: the crash happens before that setting is read, so it does not reliably help.

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,940,058 | Version: 2026.7 just released