[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:

 

 

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:

 

⚠️ 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