DEV Community

IronSoftware
IronSoftware

Posted on

Aspose System.Drawing.Common Linux: PlatformNotSupportedException Fix

#csharp #dotnet

Developers deploying Aspose.Html or Aspose.PDF to Linux environments encounter System.PlatformNotSupportedException because these libraries depend on System.Drawing.Common, which Microsoft deprecated for non-Windows platforms starting with .NET 6. This architectural dependency blocks Linux and container deployments without workarounds. This article documents the issue and examines alternatives designed for cross-platform use.

The Problem

Aspose.Html and Aspose.PDF use System.Drawing.Common for graphics operations. On Windows, System.Drawing.Common uses GDI+, a native Windows component. On Linux, it previously fell back to libgdiplus, but Microsoft deprecated this approach in .NET 6 and later.

When running on Linux with .NET 6+, any code path that uses System.Drawing.Common throws:

System.PlatformNotSupportedException: System.Drawing.Common is not supported on non-Windows platforms
Enter fullscreen mode Exit fullscreen mode

This affects:

  • HTML-to-PDF conversion
  • Image manipulation within documents
  • PDF-to-image conversion
  • Any graphics-dependent operation

Error Messages and Symptoms 

System.TypeInitializationException: The type initializer for 'Gdip' threw an exception.
 ---> System.PlatformNotSupportedException: System.Drawing.Common is not supported on non-Windows platforms.
See https://aka.ms/systemdrawingnonwindows for more information.
Enter fullscreen mode Exit fullscreen mode

Full stack trace typically includes:

   at System.Drawing.SafeNativeMethods.Gdip.GdiplusStartup(IntPtr& token, StartupInput& input, IntPtr& output)
   at System.Drawing.SafeNativeMethods.Gdip..cctor()
   --- End of inner exception stack trace ---
   at System.Drawing.SafeNativeMethods.Gdip.GdipCreateBitmapFromScan0(Int32 width, Int32 height, Int32 stride, PixelFormat format, IntPtr scan0, IntPtr& bitmap)
   at System.Drawing.Bitmap..ctor(Int32 width, Int32 height, PixelFormat format)
   at Aspose.Html.Rendering.Image.ImageDevice.CreateBitmap(Int32 width, Int32 height)
Enter fullscreen mode Exit fullscreen mode

A second common stack trace appears during PDF rendering:

Unhandled exception. System.TypeInitializationException: The type initializer for 'Gdip' threw an exception.
 ---> System.PlatformNotSupportedException: System.Drawing.Common is not supported on non-Windows platforms.
   at System.Drawing.LibraryResolver.EnsureRegistered()
   at System.Drawing.SafeNativeMethods.Gdip..cctor()
   --- End of inner exception stack trace ---
   at System.Drawing.Graphics.FromImage(Image image)
   at Aspose.Html.Converters.Converter.ConvertHTML(HTMLDocument document, PdfSaveOptions options, ICreateStreamProvider provider)
Enter fullscreen mode Exit fullscreen mode

Symptoms include:

  • Application works on Windows development machine, fails in Linux production
  • Docker builds succeed but containers crash on first graphics operation
  • CI/CD pipelines fail during integration tests on Linux runners
  • Azure App Service (Linux) deployments fail at runtime

Who Is Affected

This issue impacts any Linux deployment using Aspose.Html or Aspose.PDF:

Operating Systems: Ubuntu, Debian, Alpine, Amazon Linux, and any Linux distribution. This includes WSL2 on Windows ARM64 devices.

Framework Versions: .NET 6, .NET 7, .NET 8, and all future versions. .NET 5 and earlier allowed System.Drawing.Common on Linux but with libgdiplus dependency issues.

Deployment Environments: Docker containers, Kubernetes, AWS Lambda, Azure Functions (Linux), Azure App Service (Linux), and any cloud-native Linux infrastructure.

Affected Versions: Aspose.Html 24.10.0 through current versions.

Evidence from the Developer Community

Timeline

Date Event Source
2024-10-30 System.Drawing.Common exception reported on Linux Aspose Forums
2024-11-15 Multiple versions tested (24.10.0, 24.11.0, 24.12.0), all fail Aspose Forums
2025-08-10 Issue still being investigated Aspose Forums

Community Reports

"Drawing but facing the below error - System.TypeInitializationException: The type initializer for 'Gdip' threw an exception. PlatformNotSupportedException: System.Drawing.Common is not supported on non-Windows platforms."
— Developer, Aspose Forums, October 2024

From the error messages:

See Breaking change: System.Drawing.Common only supported on Windows
Enter fullscreen mode Exit fullscreen mode

Official Response

"We are looking into it and will be sharing our feedback with you shortly."
— Aspose Support, October 2024

Root Cause Analysis

Microsoft made a deliberate breaking change in .NET 6: System.Drawing.Common is only supported on Windows. The official documentation states:

"System.Drawing.Common will be supported only on Windows. Using System.Drawing.Common on non-Windows platforms will throw a PlatformNotSupportedException at run time."

This decision was made because:

  1. libgdiplus is unmaintained: The Mono project's libgdiplus has known bugs and memory leaks
  2. Cross-platform consistency: Different implementations on Windows vs Linux caused inconsistent behavior
  3. Modern alternatives exist: Microsoft recommends ImageSharp, SkiaSharp, or other cross-platform libraries

Aspose's libraries were designed around System.Drawing.Common. Migrating to a different graphics library would require significant architectural changes to their products.

The RuntimeConfig Workaround

Developers can technically re-enable System.Drawing.Common on Linux with a runtime configuration. There are multiple ways to apply this setting:

Method 1: runtimeconfig.json file

Create or modify [YourApp].runtimeconfig.json in your publish directory:

{
  "runtimeOptions": {
    "tfm": "net8.0",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "8.0.0"
    },
    "configProperties": {
      "System.Drawing.EnableUnixSupport": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Method 2: MSBuild property in .csproj

Add to your project file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <RuntimeHostConfigurationOption Include="System.Drawing.EnableUnixSupport" Value="true" />
  </PropertyGroup>
</Project>
Enter fullscreen mode Exit fullscreen mode

Method 3: Environment variable

Set at runtime or in Docker:

export DOTNET_SYSTEM_DRAWING_ENABLEUNIXSUPPORT=true
Enter fullscreen mode Exit fullscreen mode

However, enabling this switch re-enables the deprecated, buggy libgdiplus dependency with all its problems:

  • Memory leaks documented for years
  • Inconsistent rendering vs Windows
  • Unmaintained codebase
  • Not a sustainable long-term solution
  • Microsoft explicitly warns against using this approach

Attempted Workarounds

Workaround 1: Enable Unix Support Flag

Approach: Set the runtime configuration switch to re-enable System.Drawing.Common on Linux.

// runtimeconfig.json
{
  "runtimeOptions": {
    "configProperties": {
      "System.Drawing.EnableUnixSupport": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Also requires installing libgdiplus:

RUN apt-get update && apt-get install -y libgdiplus
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Uses deprecated, unmaintained libgdiplus
  • Memory leaks from libgdiplus affect production stability
  • Rendering may differ from Windows
  • Microsoft explicitly recommends against this approach

Workaround 2: Use Windows Containers

Approach: Deploy to Windows containers or VMs instead of Linux.

FROM mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-1809
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Windows containers are larger than Linux containers
  • Fewer hosting options in cloud environments
  • Higher licensing and infrastructure costs
  • Loses benefits of Linux-native deployment

Workaround 3: Use Aspose.PDF.Drawing

Approach: Switch to the Aspose.PDF.Drawing package, which is marketed as System.Drawing-independent.

Limitations:

  • Aspose.PDF.Drawing still has issues on Linux
  • Missing features compared to main Aspose.PDF package
  • May have its own limitations and bugs
  • Developers report evaluation watermarks on images

Troubleshooting Checklist

Before attempting workarounds, verify your environment configuration:

Step 1: Confirm .NET Version 

dotnet --version
# .NET 6.0 or later triggers this issue
Enter fullscreen mode Exit fullscreen mode

Step 2: Check Target Framework

Verify your project targets .NET 6+:

grep -i targetframework *.csproj
# <TargetFramework>net8.0</TargetFramework>
Enter fullscreen mode Exit fullscreen mode

Step 3: Verify Linux Distribution 

cat /etc/os-release
# Works on Ubuntu, Debian, Alpine, Amazon Linux
Enter fullscreen mode Exit fullscreen mode

Step 4: Check for libgdiplus (if attempting workaround) 

ldconfig -p | grep libgdiplus
# Should show: libgdiplus.so.0 if installed
Enter fullscreen mode Exit fullscreen mode

Step 5: Verify Aspose Package Version 

dotnet list package | grep -i aspose
# Note: Issue affects all recent versions
Enter fullscreen mode Exit fullscreen mode

Step 6: Test in Isolation

Create a minimal reproduction:

// TestSystemDrawing.cs
using System.Drawing;

try
{
    using var bitmap = new Bitmap(100, 100);
    Console.WriteLine("System.Drawing.Common works");
}
catch (PlatformNotSupportedException ex)
{
    Console.WriteLine($"System.Drawing.Common not supported: {ex.Message}");
}
Enter fullscreen mode Exit fullscreen mode

ASP.NET Core Specific Configuration

For ASP.NET Core applications running in Linux containers, additional configuration may be required:

Program.cs configuration:

var builder = WebApplication.CreateBuilder(args);

// Add this if attempting the libgdiplus workaround
if (OperatingSystem.IsLinux())
{
    // Log warning that System.Drawing workaround is in use
    builder.Logging.AddConsole();
    var logger = builder.Services.BuildServiceProvider()
        .GetRequiredService<ILogger<Program>>();
    logger.LogWarning("Running on Linux with System.Drawing workaround enabled");
}
Enter fullscreen mode Exit fullscreen mode

Docker Compose for Kubernetes:

version: '3.8'
services:
  pdf-service:
    build: .
    environment:
      - DOTNET_SYSTEM_DRAWING_ENABLEUNIXSUPPORT=true
      - ASPNETCORE_ENVIRONMENT=Production
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
Enter fullscreen mode Exit fullscreen mode

Kubernetes Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pdf-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: pdf-service
  template:
    spec:
      containers:
      - name: pdf-service
        image: your-registry/pdf-service:latest
        env:
        - name: DOTNET_SYSTEM_DRAWING_ENABLEUNIXSUPPORT
          value: "true"
        resources:
          limits:
            memory: "2Gi"
          requests:
            memory: "1Gi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
Enter fullscreen mode Exit fullscreen mode

A Different Approach: IronPDF

IronPDF is designed for cross-platform deployment without System.Drawing.Common dependency. It uses Chromium's rendering engine, which is natively available for Linux.

Why IronPDF Works on Linux

IronPDF's architecture differs from libraries built on System.Drawing:

  1. No System.Drawing dependency: IronPDF does not use System.Drawing.Common
  2. Native Linux binaries: Chromium binaries are compiled for Linux x64 and ARM64
  3. Docker-ready: Official Docker images and documentation for container deployment
  4. Cross-platform parity: Same behavior on Windows, Linux, and macOS

Code Example 

using IronPdf;

public class CrossPlatformConverter
{
    public byte[] ConvertHtmlToPdf(string html)
    {
        // Works identically on Windows, Linux, macOS
        var renderer = new ChromePdfRenderer();

        renderer.RenderingOptions.MarginTop = 25;
        renderer.RenderingOptions.MarginBottom = 25;
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;

        using var pdf = renderer.RenderHtmlAsPdf(html);
        return pdf.BinaryData;
    }
}
Enter fullscreen mode Exit fullscreen mode

Docker deployment:

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim

# IronPDF Linux dependencies
RUN apt-get update && apt-get install -y \
    libc6 \
    libgcc-s1 \
    libgssapi-krb5-2 \
    libicu72 \
    libssl3 \
    libstdc++6 \
    zlib1g \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]
Enter fullscreen mode Exit fullscreen mode

Key points about this code:

  • No System.Drawing.Common dependency
  • Works on Linux without special configuration flags
  • No libgdiplus installation required
  • Same code runs on all platforms

API Reference

For more details on cross-platform deployment:

Migration Considerations

Licensing

  • IronPDF is commercial software with perpetual licensing
  • Free trial available for evaluation
  • Licensing details

API Differences

  • Migration requires replacing Aspose.Html/PDF conversion calls
  • HTML templates typically do not need modification
  • API is straightforward: pass HTML, get PDF

What You Gain

  • True cross-platform support without workarounds
  • No System.Drawing.Common dependency
  • Works in Docker, Kubernetes, serverless environments
  • Predictable behavior across all platforms

What to Consider

  • Chromium binaries increase deployment size
  • Different pricing model
  • Different API surface

Conclusion

Aspose.Html and Aspose.PDF's dependency on System.Drawing.Common creates deployment failures on Linux with .NET 6 and later. The available workarounds either use deprecated, buggy components or restrict deployments to Windows. For applications targeting Linux or containerized environments, libraries designed without System.Drawing.Common dependency provide a more sustainable path forward.

Jacob Mellor originally built IronPDF and leads Iron Software's technical vision.

References

  1. Aspose Forum Thread #293413{:rel="nofollow"} - System.Drawing.Common not supported on non-Windows
  2. Microsoft: System.Drawing.Common only supported on Windows{:rel="nofollow"} - Official documentation

For the latest IronPDF documentation and tutorials, visit ironpdf.com.

Top comments (0)