Deployment Troubleshooting for Azure Linux App Service

Curtis Chau

Updated: August 2, 2026

Download IronPDF

• NuGet Download
• DLL Download
• Windows Installer

• ---

• Start Free Trial

Copy for LLMs

• Copy for LLMs

  Copy page as Markdown for LLMs
  # Deployment Troubleshooting for Azure Linux App Service When deploying IronPDF to an Azure Linux App Service, the application may fail to render PDFs due to missing system libraries. This occurs because Linux environments come with fewer pre-installed packages than Windows, and the IronPDF rendering engine requires additional shared libraries to operate. ```txt 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') ``` The error means that one or more shared libraries required by `IronInterop.so` are absent from the Linux environment. Running `ldd IronInterop.so` from the SSH console on the app service identifies exactly which libraries are missing. The read-only filesystem message for the runtimes folder is a separate symptom of the same missing-dependency condition. ## Solution ### Step 1: Identify missing dependencies 1. Deploy the app service from Visual Studio as normal. 2. Open the SSH console for your Azure Linux App Service. 3. Navigate to the wwwroot directory: ```shell cd /home/site/wwwroot ``` 4. Run `ldd` against the native binary to list unresolved dependencies: ```txt ldd IronInterop.so ``` 5. Check the OS version to confirm which package names apply: ```txt cat /etc/os-release ``` ### Step 2: Install missing libraries For most Linux distributions (Debian/Ubuntu-based images), install the required packages with: ```shell apt-get update && apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libxkbcommon0 libasound2 libatspi2.0-0 ``` For Ubuntu 24.04 images (used with .NET 10), use the following Dockerfile instruction instead, as some package names have changed: ```dockerfile RUN apt update \ && apt install -y sudo libxkbcommon-x11-0 libc6 libc6-dev libgtk2.0-0t64 libnss3 libatk-bridge2.0-0t64 libx11-xcb1 libxcb-dri3-0 libdrm-common libgbm1 libasound2t64 libxrender1 libfontconfig1 libxshmfence1 libgdiplus libva-dev ``` ### Step 3: Verify all dependencies are resolved Run `ldd` again to confirm there are no remaining unresolved entries: ```txt ldd IronInterop.so ``` All entries should show a resolved path rather than `not found`. Once all dependencies are in place, PDF rendering through the web application will work normally. For the full list of required packages across Linux distributions, see the [Linux deployment guide](/get-started/linux/).

• ---

• Open in ChatGPT

  Ask ChatGPT about this page
• Open in Gemini

  Ask Gemini about this page
• Open in Grok

  Ask Grok about this page
• Open in Perplexity

  Ask Perplexity about this page

Share

• Share on Facebook
• Share on X (Twitter)
• Share on LinkedIn

• ---

• Email article

When deploying IronPDF to an Azure Linux App Service, the application may fail to render PDFs due to missing system libraries. This occurs because Linux environments come with fewer pre-installed packages than Windows, and the IronPDF rendering engine requires additional shared libraries to operate.

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')

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')

The error means that one or more shared libraries required by IronInterop.so are absent from the Linux environment. Running ldd IronInterop.so from the SSH console on the app service identifies exactly which libraries are missing. The read-only filesystem message for the runtimes folder is a separate symptom of the same missing-dependency condition.

Solution

Step 1: Identify missing dependencies

1. Deploy the app service from Visual Studio as normal.

2. Open the SSH console for your Azure Linux App Service.

3. Navigate to the wwwroot directory:

   cd /home/site/wwwroot

   SHELL

4. Run ldd against the native binary to list unresolved dependencies:

   ldd IronInterop.so

   Text

5. Check the OS version to confirm which package names apply:

   cat /etc/os-release

   Text

Step 2: Install missing libraries

For most Linux distributions (Debian/Ubuntu-based images), install the required packages with:

apt-get update && apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libxkbcommon0 libasound2 libatspi2.0-0

apt-get update && apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libxkbcommon0 libasound2 libatspi2.0-0

For Ubuntu 24.04 images (used with .NET 10), use the following Dockerfile instruction instead, as some package names have changed:

RUN apt update \
    && apt install -y sudo libxkbcommon-x11-0 libc6 libc6-dev libgtk2.0-0t64 libnss3 libatk-bridge2.0-0t64 libx11-xcb1 libxcb-dri3-0 libdrm-common libgbm1 libasound2t64 libxrender1 libfontconfig1 libxshmfence1 libgdiplus libva-dev

RUN apt update \
    && apt install -y sudo libxkbcommon-x11-0 libc6 libc6-dev libgtk2.0-0t64 libnss3 libatk-bridge2.0-0t64 libx11-xcb1 libxcb-dri3-0 libdrm-common libgbm1 libasound2t64 libxrender1 libfontconfig1 libxshmfence1 libgdiplus libva-dev

Step 3: Verify all dependencies are resolved

Run ldd again to confirm there are no remaining unresolved entries:

ldd IronInterop.so

ldd IronInterop.so

All entries should show a resolved path rather than not found. Once all dependencies are in place, PDF rendering through the web application will work normally. For the full list of required packages across Linux distributions, see the Linux deployment guide.

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