Fix IronPdfEngine Docker Connection Failures on macOS ARM

Curtis Chau

Updated: June 10, 2026

Download IronPDF

• NuGet Download
• DLL Download
• Windows Installer

• ---

• Start Free Trial

Copy for LLMs

• Copy for LLMs

  Copy page as Markdown for LLMs
  # Fix IronPdfEngine Docker Connection Failures on macOS ARM When connecting a .NET application to IronPdfEngine via Docker on a macOS ARM device (Apple Silicon), the application throws: ```txt Unhandled exception. System.IO.FileNotFoundException: Error loading native library. Not found in any of the possible locations ``` `IronPdfConnectionType.Docker` uses an older gRPC implementation that does not support ARM architecture. On macOS ARM (Apple Silicon), the .NET client cannot load the required native gRPC binary, even when the Docker image is forced to run as `--platform linux/amd64`. Windows and Linux x64 platforms are not affected. ## Solution Replace `IronPdfConnectionType.Docker` with `IronPdfConnectionType.RemoteServer` in the connection configuration. `RemoteServer` uses a newer gRPC implementation that is ARM-compatible: ```csharp using IronPdf; var config = new IronPdfConnectionConfiguration { ConnectionType = IronPdfConnectionType.RemoteServer, Host = "http://127.0.0.1", Port = 33350 }; IronPdf.Installation.ConnectToIronPdfHost(config); IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY"); var renderer = new ChromePdfRenderer(); var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Hello from IronPdfEngine</h1>"); pdf.SaveAs("output.pdf"); ``` **Requirements:** - The IronPdfEngine Docker container must be running and reachable at the specified host and port before calling `ConnectToIronPdfHost`. - Use `http://`, not `https://`; using `https://` without a valid SSL certificate causes frame corruption errors in the gRPC channel. See also: [troubleshooting Vulkan/ANGLE initialization errors in Docker](https://ironpdf.com/troubleshooting/vulkan-angle-initialization-docker/) and [fixing gRPC connection errors in Azure Containers](https://ironpdf.com/troubleshooting/azure-grpc-connection-errors/).

• ---

• 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 connecting a .NET application to IronPdfEngine via Docker on a macOS ARM device (Apple Silicon), the application throws:

Unhandled exception. System.IO.FileNotFoundException: Error loading native library.
Not found in any of the possible locations

Unhandled exception. System.IO.FileNotFoundException: Error loading native library.
Not found in any of the possible locations

IronPdfConnectionType.Docker uses an older gRPC implementation that does not support ARM architecture. On macOS ARM (Apple Silicon), the .NET client cannot load the required native gRPC binary, even when the Docker image is forced to run as --platform linux/amd64. Windows and Linux x64 platforms are not affected.

Solution

Replace IronPdfConnectionType.Docker with IronPdfConnectionType.RemoteServer in the connection configuration. RemoteServer uses a newer gRPC implementation that is ARM-compatible:

using IronPdf;

var config = new IronPdfConnectionConfiguration
{
    ConnectionType = IronPdfConnectionType.RemoteServer,
    Host = "http://127.0.0.1",
    Port = 33350
};

IronPdf.Installation.ConnectToIronPdfHost(config);

IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY");

var renderer = new ChromePdfRenderer();
var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Hello from IronPdfEngine</h1>");
pdf.SaveAs("output.pdf");

using IronPdf;

var config = new IronPdfConnectionConfiguration
{
    ConnectionType = IronPdfConnectionType.RemoteServer,
    Host = "http://127.0.0.1",
    Port = 33350
};

IronPdf.Installation.ConnectToIronPdfHost(config);

IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY");

var renderer = new ChromePdfRenderer();
var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Hello from IronPdfEngine</h1>");
pdf.SaveAs("output.pdf");

Imports IronPdf

Dim config As New IronPdfConnectionConfiguration With {
    .ConnectionType = IronPdfConnectionType.RemoteServer,
    .Host = "http://127.0.0.1",
    .Port = 33350
}

IronPdf.Installation.ConnectToIronPdfHost(config)

IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY")

Dim renderer As New ChromePdfRenderer()
Dim pdf = Await renderer.RenderHtmlAsPdfAsync("<h1>Hello from IronPdfEngine</h1>")
pdf.SaveAs("output.pdf")

Imports IronPdf

Dim config As New IronPdfConnectionConfiguration With {
    .ConnectionType = IronPdfConnectionType.RemoteServer,
    .Host = "http://127.0.0.1",
    .Port = 33350
}

IronPdf.Installation.ConnectToIronPdfHost(config)

IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY")

Dim renderer As New ChromePdfRenderer()
Dim pdf = Await renderer.RenderHtmlAsPdfAsync("<h1>Hello from IronPdfEngine</h1>")
pdf.SaveAs("output.pdf")

Requirements:

• The IronPdfEngine Docker container must be running and reachable at the specified host and port before calling ConnectToIronPdfHost.
• Use http://, not https://; using https:// without a valid SSL certificate causes frame corruption errors in the gRPC channel.

See also: troubleshooting Vulkan/ANGLE initialization errors in Docker and fixing gRPC connection errors in Azure Containers.

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