IronPdfEngine Docker Connection Fails on macOS ARM Using Docker Connection Type

Issue Overview

When attempting to connect a .NET 9 Console application to the IronPdfEngine via Docker on macOS ARM devices (e.g., Apple Silicon), users may encounter the error below

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

This is due to a compatibility issue between the Docker connection type and ARM architecture.

Root Cause

• The Docker connection type in IronPdf currently uses the older gRPC implementation, which is not compatible with ARM architectures.

• macOS ARM users may also run into architecture mismatches between host (ARM) and Docker image (Linux/amd64).

• Attempting to force platform with --platform linux/amd64 allows the container to run, but the .NET C# client still fails due to missing or incompatible native gRPC binaries.

Workaround

Instead of using IronPdfConnectionType.Docker, configure the connection using RemoteServer. This uses the newer, ARM-compatible gRPC implementation.

Example:

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

IronPdf.Installation.ConnectToIronPdfHost(config);

⚠️ Important: Ensure the Docker container is already running and accessible at the specified port. Also, use http:// instead of https:// unless SSL is properly configured.

ℹ️ Additional Notes

• Using the wrong protocol (https:// without valid SSL config) can result in the error:

  "The SSL connection could not be established. Cannot determine the frame size or a corrupted frame was received."

• This issue affects only the Docker connection type on macOS ARM. Other platforms (e.g., Windows, Linux x64) are not affected.