Chrome Renderer Fails on Cold Start in Azure App Service Linux

Updated:June 9, 2026

This issue occurs on Azure App Service Linux when the underlying Oryx/Ubuntu base image is updated by Azure, removing shared libraries that IronPDF's Chrome renderer depends on. During the next cold start, IronPDF must reinstall those native Chrome dependencies from scratch, a process that can take up to 5 minutes. If the application startup timeout is too short, the installation is interrupted and the renderer fails.

The error typically appears as:

libnss3.so: cannot open shared object file: No such file or directory

Azure periodically updates the base image used by App Service Linux environments. These updates can remove shared libraries such as libnss3.so that Chrome requires. When this happens, IronPDF's LinuxAndDockerDependenciesAutoConfig mechanism attempts to reinstall the required packages on startup. If the service timeout is shorter than the time needed to complete this installation, the process is cut off before Chrome is ready.

This issue has been confirmed in the following environment:

Affected version: IronPDF 2026.4.1
Unaffected version: IronPDF 2026.5.2
Hosting: Azure App Service P0v3 plan, Norway East region
Runtime: .NET 10

Solution

Solution 1: Apply initialization settings and increase the startup timeout

Add the following initialization code at application startup, before any PDF rendering calls:

Logger.LoggingMode = Logger.LoggingModes.All;
Installation.LinuxAndDockerDependenciesAutoConfig = true;
Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled;
Installation.Initialize();

Logger.LoggingMode = Logger.LoggingModes.All;
Installation.LinuxAndDockerDependenciesAutoConfig = true;
Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled;
Installation.Initialize();

Option Strict On
Option Infer On

Logger.LoggingMode = Logger.LoggingModes.All
Installation.LinuxAndDockerDependenciesAutoConfig = True
Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled
Installation.Initialize()

$vbLabelText $csharpLabel

Setting LinuxAndDockerDependenciesAutoConfig to true tells IronPDF to detect and install missing Linux dependencies automatically. Setting ChromeGpuMode to IronPdf.Engines.Chrome.ChromeGpuModes.Disabled turns off GPU acceleration, which is not available in Azure App Service Linux environments. Enabling full logging helps capture any errors during the dependency installation step.

Next, increase the Azure App Service startup timeout to at least 10 minutes. This gives IronPDF enough time to complete dependency reinstallation during a cold start following an Azure base image update. See the Azure deployment guide for instructions on adjusting the startup time limit setting in App Service configuration.

Solution 2: Upgrade to IronPDF 2026.5.2 or later

Upgrading to IronPDF 2026.5.2 or a later version resolves this issue. The unaffected version handles the case where Azure base image updates remove shared libraries without causing a cold start failure.

ImportantThis issue was resolved in IronPDF 2026.5.2. If you are on that version or later, the workarounds in Solution 1 are no longer required.

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,345,590 | Version: 2026.6 just released