[Public] Troubleshooting IronPDF on Azure Linux App Services with WEBSITE_RUN_FROM_PACKAGE Enabled

Overview

By right, IronPDF encourage users to disable WEBSITE_RUN_FROM_PACKAGE when deploying to Azure.

https://ironpdf.com/troubleshooting/502-bad-gateway/

If enable WEBSITE_RUN_FROM_PACKAGE, what to do?

When deploying a .NET Core API using IronPDF on an Azure Linux App Service with WEBSITE_RUN_FROM_PACKAGE enabled, you may encounter deployment errors related to missing native libraries and system write access. This article outlines the root cause of the issue, workarounds, and recommended solutions.

 

---

Problem

 

Running IronPDF in an Azure Linux App Service configured with WEBSITE_RUN_FROM_PACKAGE fails with errors such as:

Error while deploying IronPdf Chrome renderer:
'Multiple issues occurred while trying to deploy Chrome
(libatk-1.0.so.0: cannot open shared object file: No such file or directory)
(IronInterop.so: cannot open shared object file: No such file or directory)
(Read-only file system: '/home/site/wwwroot/runtimes')'

 

Key Symptoms:

• The app fails only when WEBSITE_RUN_FROM_PACKAGE is enabled.

• Errors indicate missing dependencies (e.g., libatk-1.0.so.0) and filesystem write errors.

• IronPDF cannot extract required files due to the read-only file system imposed by WEBSITE_RUN_FROM_PACKAGE.

---

Understanding Root Cause

 

IronPDF requires native libraries and runtime Chrome components that must:

1. Be extracted to a writable file system.

2. Access dynamic system libraries (e.g., libatk, libnss3, etc.).

When WEBSITE_RUN_FROM_PACKAGE is enabled:

• The /home/site/wwwroot directory becomes read-only, preventing IronPDF from deploying its Chrome renderer.

• Linux dependencies may not be pre-installed on the default Azure Linux App Service, leading to missing .so file errors.

---

Workarounds & Solutions

 

Option 1: Manually Install Required Dependencies (Temporary Solution)

If your app service allows outbound SSH access and your deployment can tolerate runtime installation:

1. Navigate to your Azure App Service → Development Tools → SSH.

2. Run the following commands to install required system packages:

apt update
apt install -y libc6-dev libgtk2.0-0 libnss3 libatk-bridge2.0-0 \
libx11-xcb1 libxcb-dri3-0 libdrm-common libgbm1 libasound2 \
libxkbcommon-x11-0 libxrender1 libfontconfig1 libxshmfence1

This approach is not recommended for production environments that cannot guarantee access to APT repositories due to firewall or outbound restrictions.

---

Option 2: Use a Custom Linux Docker Container (Recommended for Linux)

 

Build a Docker container image with all dependencies and IronPDF packages pre-installed.

1. Base your Dockerfile on a compatible Linux distro (e.g., ubuntu, debian).

2. Install all required packages via apt.

3. Include all IronPDF NuGet packages in the build.

See: https://ironpdf.com/get-started/ironpdf-docker/

 

---

 

Option 3: Switch to Windows App Service

 

IronPDF is natively supported and tested on Windows App Services, where:

• All required DLLs are present or auto-extracted.

• WEBSITE_RUN_FROM_PACKAGE works without filesystem permission issues.

If Docker is not an option and runtime installation is restricted, migrating to a Windows App Service is the most straightforward alternative.

 

---

Required NuGet Packages

 

Ensure the following NuGet packages are added to your project to avoid runtime package download issues:

• IronPdf

• IronPdf.Native.Chrome.Linux (exact version used in your build)

 

Add them to your .csproj file to pre-resolve at build time and avoid runtime dependency download attempts.

---

Summary