How to Configure Proxy Servers for PDF Rendering in C#

Updated: August 2, 2026

Proxy configuration in IronPDF is a method parameter on RenderHtmlAsPdf() overloads - not a property on ChromePdfRenderOptions. This distinction matters because RenderUrlAsPdf() has no proxy parameter at all, which requires a different strategy when you need to render live URLs behind a corporate proxy. If you pass null (the default), IronPDF connects directly.

This guide covers every proxy scenario you will encounter in production: direct proxy strings, authenticated corporate proxies, the RenderUrlAsPdf workaround, Docker container configuration, CI/CD pipeline integration, and common troubleshooting patterns for SSL interception and NTLM authentication.

Start a free 30-day trial to test proxy configurations in your environment.

Quickstart: Render PDFs Through a Proxy

IronPDF's optional proxy parameter helps you convert live web pages served behind corporate proxies. Use this code snippet to get started quickly.

1Install IronPDF with NuGet Package Manager
PM > Install-Package IronPdf
```
Install-Package IronPdf
```

2Copy and run this code snippet.

using IronPdf;

var renderer = new ChromePdfRenderer();

// Proxy is the third parameter — not a render option
PdfDocument pdf = renderer.RenderHtmlAsPdf(
    "<h1>Hello from behind the proxy</h1>",
    baseUrlOrPath: null,
    proxy: "http://proxy.corp.local:8080"
);
pdf.SaveAs("proxied-output.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

// Proxy is the third parameter — not a render option
PdfDocument pdf = renderer.RenderHtmlAsPdf(
    "<h1>Hello from behind the proxy</h1>",
    baseUrlOrPath: null,
    proxy: "http://proxy.corp.local:8080"
);
pdf.SaveAs("proxied-output.pdf");

3Deploy to test on your live environment

Start using IronPDF in your project today with a free trial

Minimal Workflow (3 Steps)

Install IronPDF via NuGet: Install-Package IronPdf
Pass the proxy string as the third parameter to RenderHtmlAsPdf
Format: http(s)://host:port or http(s)://user:pass@host:port for authenticated proxies

How Do You Pass a Proxy to `RenderHtmlAsPdf`?

The Proxy parameter is an optional string on four method signatures:

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

' Instance methods
Function RenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Proxy As String = Nothing) As PdfDocument
End Function

Function RenderHtmlAsPdf(Html As String, Optional BaseUrl As Uri = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Static methods
Shared Function StaticRenderHtmlAsPdf(Html As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Shared Function StaticRenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Instance methods
Function RenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Proxy As String = Nothing) As PdfDocument
End Function

Function RenderHtmlAsPdf(Html As String, Optional BaseUrl As Uri = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Static methods
Shared Function StaticRenderHtmlAsPdf(Html As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Shared Function StaticRenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

When this parameter is null (the default), IronPDF's Chromium engine connects directly to external resources - stylesheets, images, fonts, and JavaScript files referenced in your HTML. When you provide a proxy string, all HTTP/HTTPS requests from the rendering engine route through that proxy.

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Direct connection (default — no proxy)
Dim pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>")

' Through an unauthenticated proxy
Dim pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath:=Nothing,
    proxy:="http://squid.internal:3128"
)

' Using the Uri overload
Dim pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl:=New Uri("https://assets.example.com/"),
    proxy:="https://proxy.corp.local:8443"
)

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Direct connection (default — no proxy)
Dim pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>")

' Through an unauthenticated proxy
Dim pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath:=Nothing,
    proxy:="http://squid.internal:3128"
)

' Using the Uri overload
Dim pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl:=New Uri("https://assets.example.com/"),
    proxy:="https://proxy.corp.local:8443"
)

The proxy string supports both http:// and https:// schemes. Use https:// when the proxy itself requires TLS encryption for the connection between your application and the proxy server. The scheme here refers to the proxy connection, not the final resource - an http:// proxy can still fetch https:// resources via CONNECT tunneling.

The static method variants accept the same proxy parameter, which is useful for one-off renders in console applications or unit tests:

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

' Static render with proxy — no renderer instance needed
Dim pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options:=Nothing,
    proxy:="http://proxy.corp.local:8080"
)

' Static render with proxy — no renderer instance needed
Dim pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options:=Nothing,
    proxy:="http://proxy.corp.local:8080"
)

Important: There is no Proxy property on ChromePdfRenderOptions. Do not look for it there. The proxy is strictly a method parameter on RenderHtmlAsPdf and FromHtml overloads.

How Do You Authenticate with a Corporate Proxy?

Most enterprise proxies require credentials. You embed them directly in the proxy URL using the http(s)://username:password@host:port format:

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

Dim proxyWithAuth As String = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: "C:\templates\assets\",
    proxy:=proxyWithAuth
)
pdf.SaveAs("report.pdf")

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

Dim proxyWithAuth As String = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: "C:\templates\assets\",
    proxy:=proxyWithAuth
)
pdf.SaveAs("report.pdf")

URL-encode special characters in passwords. If your password contains @, #, :, /, or other reserved URI characters, they must be percent-encoded. Common encodings:

Character	Encoded
`@`	`%40`
`#`	`%23`
`:`	`%3A`
`/`	`%2F`
`!`	`%21`
`%`	`%25`

Use Uri.EscapeDataString() to encode the password programmatically:

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

Imports System

Dim rawPassword As String = "P@ssw0rd!"
Dim encoded As String = Uri.EscapeDataString(rawPassword) ' "P%40ssw0rd%21"
Dim proxy As String = $"http://svc-account:{encoded}@proxy.corp.local:8080"

Imports System

Dim rawPassword As String = "P@ssw0rd!"
Dim encoded As String = Uri.EscapeDataString(rawPassword) ' "P%40ssw0rd%21"
Dim proxy As String = $"http://svc-account:{encoded}@proxy.corp.local:8080"

Do not confuse proxy authentication with web page authentication. The ChromeHttpLoginCredentials.NetworkUsername and NetworkPassword properties authenticate against the web page being rendered (NTLM/Negotiate with a website), not against a proxy server. For proxy auth, the credentials go in the proxy URL string as shown above.

How Do You Render URLs Behind a Proxy?

RenderUrlAsPdf does not accept a proxy parameter. This is a deliberate API design choice - NavigateUrl navigates Chromium to a URL, and the proxy configuration for that navigation is handled differently than for resource loading during HTML rendering.

The recommended workaround: fetch the HTML yourself using HttpClient configured with a HttpProxy, then pass the HTML string to RenderHtmlAsPdf with the proxy parameter (so that referenced assets - images, CSS, fonts - also route through the proxy).

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

Imports IronPdf
Imports System.Net
Imports System.Net.Http

' Step 1: Configure HttpClient with the corporate proxy
Dim proxy As New WebProxy("http://proxy.corp.local:8080") With {
    .Credentials = New NetworkCredential("svc-account", "P@ssw0rd!")
}

Dim handler As New HttpClientHandler With {
    .Proxy = proxy,
    .UseProxy = True
}

Using httpClient As New HttpClient(handler)
    ' Step 2: Fetch the HTML from the target URL
    Dim targetUrl As String = "https://dashboard.internal.corp/quarterly-report"
    Dim html As String = Await httpClient.GetStringAsync(targetUrl)

    ' Step 3: Render the fetched HTML, with the proxy for asset loading
    Dim renderer As New ChromePdfRenderer()

    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
        html,
        baseUrlOrPath:=targetUrl,  ' Resolves relative asset paths against the original URL
        proxy:="http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

Imports IronPdf
Imports System.Net
Imports System.Net.Http

' Step 1: Configure HttpClient with the corporate proxy
Dim proxy As New WebProxy("http://proxy.corp.local:8080") With {
    .Credentials = New NetworkCredential("svc-account", "P@ssw0rd!")
}

Dim handler As New HttpClientHandler With {
    .Proxy = proxy,
    .UseProxy = True
}

Using httpClient As New HttpClient(handler)
    ' Step 2: Fetch the HTML from the target URL
    Dim targetUrl As String = "https://dashboard.internal.corp/quarterly-report"
    Dim html As String = Await httpClient.GetStringAsync(targetUrl)

    ' Step 3: Render the fetched HTML, with the proxy for asset loading
    Dim renderer As New ChromePdfRenderer()

    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
        html,
        baseUrlOrPath:=targetUrl,  ' Resolves relative asset paths against the original URL
        proxy:="http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

The baseUrlOrPath parameter is set to the original target URL so that relative paths in the fetched HTML (<img src="/images/logo.png">, <link href="/css/styles.css">) resolve correctly. The proxy parameter ensures those asset requests route through the proxy during rendering.

This pattern also works with pages behind authentication - configure the HttpClient with the appropriate cookies or headers before fetching, then pass the authenticated HTML to IronPDF. The HTTP request header how-to covers header configuration for authenticated requests.

If the page relies on JavaScript for rendering (SPAs, React dashboards, Angular apps), the fetched HTML will only contain the initial shell - client-side rendering will not execute during the HttpClient fetch. For those cases, you have two options: set system-level HTTP_PROXY/HTTPS_PROXY environment variables (covered in the next section) so that RenderUrlAsPdf() routes through the proxy at the OS level, or use a headless browser to fetch the fully-rendered HTML before passing it to RenderHtmlAsPdf().

My favorite library of this kind is IronPDF. It allows for fast and efficient manipulation of PDF files. It also has many valuable features, like exporting to PDF/A format and digitally signing PDF documents.

Milan Jovanovic

Microsoft MVP

View case study

IronOCR means we can save $40,000 annually from manual processing, while enhancing productivity and freeing up resources for high-impact tasks. I would highly recommend it.

Brent Matzelle

Chief Technology Officer, OPYN

View case study

How Do You Configure Proxy in Docker Containers?

In containerized environments, you may prefer system-level proxy configuration over per-method parameters. IronPDF's Chromium engine respects the standard HTTP_PROXY and HTTPS_PROXY environment variables that Linux containers use for outbound traffic routing.

Set these in your Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# System-level proxy for all outbound HTTP/HTTPS traffic
ENV HTTP_PROXY=http://proxy.corp.local:8080
ENV HTTPS_PROXY=http://proxy.corp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.corp

# Install IronPDF dependencies (fonts, etc.)
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# System-level proxy for all outbound HTTP/HTTPS traffic
ENV HTTP_PROXY=http://proxy.corp.local:8080
ENV HTTPS_PROXY=http://proxy.corp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.corp

# Install IronPDF dependencies (fonts, etc.)
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Text

With these environment variables set, you can call RenderHtmlAsPdf without the proxy parameter - Chromium picks up the system-level configuration automatically:

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

' No proxy parameter needed — Chromium uses HTTP_PROXY env var
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)

' No proxy parameter needed — Chromium uses HTTP_PROXY env var
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)

NO_PROXY is important for internal resources. Without it, requests to internal services (like a local CSS server or image CDN running inside your Kubernetes cluster) would unnecessarily route through the proxy. Comma-separate the hostnames and domains that should bypass the proxy.

If you need both system-level proxy for general traffic and a different proxy for specific renders, the method parameter takes precedence over the environment variable. This gives you per-render control when needed.

For Kubernetes deployments, inject the same proxy environment variables into your pod spec, typically sourced from a ConfigMap:

# Kubernetes pod spec
spec:
  containers:
    - name: pdf-generator
      image: myregistry/pdf-service:latest
      env:
        - name: HTTP_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: http-proxy
        - name: HTTPS_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: https-proxy
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.internal.corp"

# Kubernetes pod spec
spec:
  containers:
    - name: pdf-generator
      image: myregistry/pdf-service:latest
      env:
        - name: HTTP_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: http-proxy
        - name: HTTPS_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: https-proxy
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.internal.corp"

Text

How Do You Handle Proxy in CI/CD Pipelines?

CI/CD runners in corporate networks frequently sit behind proxies. Pass the proxy URL as a build variable or secret - never hardcode credentials in source control.

GitHub Actions:

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

Text

Azure DevOps:

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

Text

Jenkins (Declarative Pipeline):

environment {
    HTTP_PROXY  = credentials('corp-proxy-url')
    HTTPS_PROXY = credentials('corp-proxy-url')
}

environment {
    HTTP_PROXY  = credentials('corp-proxy-url')
    HTTPS_PROXY = credentials('corp-proxy-url')
}

Text

In all three cases, Chromium reads the environment variables automatically. If you prefer explicit control, read the proxy URL from the environment and pass it as the method parameter:

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

Option Strict On
Option Infer On

Dim proxy As String = Environment.GetEnvironmentVariable("HTTPS_PROXY")
Dim pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath:=Nothing, proxy:=proxy)

Option Strict On
Option Infer On

Dim proxy As String = Environment.GetEnvironmentVariable("HTTPS_PROXY")
Dim pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath:=Nothing, proxy:=proxy)

How Do You Troubleshoot Proxy Issues?

Timeout errors: Corporate proxies add latency. Increase the render timeout from the 60-second default:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

This is the RenderTimeout property - it controls how long Chromium waits for page load and resource fetching combined. If your proxy adds 5-10 seconds of latency per request, and the page loads 20+ external resources, 60 seconds may not be enough.

SSL interception (MITM proxies): Many corporate proxies decrypt and re-encrypt HTTPS traffic using a corporate root CA certificate. Chromium rejects these connections because it does not trust the corporate CA by default. Two solutions:

Install the corporate CA certificate in the container or host's trusted root store. On Linux: copy the .crt to /usr/local/share/ca-certificates/ and run update-ca-certificates.
In development only, you can disable certificate validation - but never do this in production. The safer approach is always to install the proper certificate.

NTLM authentication: The inline user:pass@host format supports Basic and Digest proxy authentication. NTLM (common in Windows-centric enterprises) is not supported through the proxy URL string. The workaround is to run a local NTLM-to-Basic forwarding proxy like CNTLM on the host or as a sidecar container. Configure CNTLM with your NTLM credentials, then point IronPDF at http://localhost:3128 (CNTLM's default port).

Blank PDF or missing assets: If the PDF renders but images/CSS are missing, your HTML references resources that the proxy blocks or that require a different proxy path. Verify that the baseUrlOrPath parameter resolves correctly through the proxy, and check the proxy's access logs for 403 or 407 responses.

Proxy bypass for local assets: If your HTML references a mix of local assets (bundled images, inline CSS) and remote resources (CDN fonts, external scripts), the proxy only needs to handle the remote requests. Set baseUrlOrPath to a local directory for file-system assets, and let the proxy handle only the network requests. This avoids routing local file reads through the proxy unnecessarily.

Diagnosing connectivity: To verify your proxy string is correct before using it with IronPDF, test it with a simple HttpClient request first:

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

Imports System
Imports System.Net
Imports System.Net.Http

Dim proxy As New WebProxy("http://proxy.corp.local:8080")
Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using client As New HttpClient(handler)
    Dim response = Await client.GetAsync("https://httpbin.org/ip")
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
    ' Should return the proxy's external IP, not your machine's IP
End Using

Imports System
Imports System.Net
Imports System.Net.Http

Dim proxy As New WebProxy("http://proxy.corp.local:8080")
Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using client As New HttpClient(handler)
    Dim response = Await client.GetAsync("https://httpbin.org/ip")
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
    ' Should return the proxy's external IP, not your machine's IP
End Using

If this succeeds but IronPDF still fails, the issue is likely SSL interception or a protocol mismatch between your proxy and Chromium's CONNECT tunneling. Check whether the proxy supports HTTP CONNECT for HTTPS resources - some proxies require explicit configuration to allow tunneling.

Next Steps

Proxy support in IronPDF is a method parameter on RenderHtmlAsPdf() - pass the proxy string, and the Chromium engine routes all HTTP traffic through it. For RenderUrlAsPdf() scenarios, fetch the HTML with HttpClient and a WebProxy first. For containers and CI/CD, system-level HTTP_PROXY/HTTPS_PROXY environment variables give you infrastructure-level control without code changes.

Explore the logins and authentication how-to for web page authentication (distinct from proxy auth), the HTTP request header guide for custom headers, and the rendering options reference for timeout and performance tuning.

View licensing options starting at $999. The ChromePdfRenderer API reference documents every method overload and the ChromePdfRenderOptions reference covers all configurable properties.

Frequently Asked Questions

How do you configure a proxy for PDF rendering in IronPDF?

In IronPDF, the proxy is configured via a method parameter in the `RenderHtmlAsPdf()` overloads, not as a property in `ChromePdfRenderOptions`. You provide the proxy URL as a string parameter, enabling HTTP/HTTPS requests to route through the specified proxy server.

Can you use IronPDF with authenticated proxies?

Yes, you can use authenticated proxies with IronPDF by embedding credentials directly in the proxy URL using the `http(s)://username:password@host:port` format. Make sure to URL-encode special characters in passwords.

What should you do if `RenderUrlAsPdf()` does not support proxies?

If `RenderUrlAsPdf()` does not support proxies, you can manually fetch the HTML with `HttpClient` configured with a `WebProxy`, and then pass the HTML to `RenderHtmlAsPdf()` with the proxy parameter included.

How do you handle proxy settings in Docker containers using IronPDF?

In Docker, set `HTTP_PROXY` and `HTTPS_PROXY` environment variables in your Dockerfile. IronPDF's Chromium engine will respect these settings for routing outbound HTTP/HTTPS traffic.

How can you troubleshoot PDF rendering proxy issues with IronPDF?

Common troubleshooting steps include increasing the render timeout to account for proxy latency, ensuring SSL certificates are correctly installed, and verifying NTLM authentication is properly configured using tools like CNTLM.

How does IronPDF interact with CI/CD pipeline proxy settings?

In CI/CD environments, pass proxy URLs as build variables or secrets for security. IronPDF's Chromium engine will automatically use these configurations unless specified differently via method parameters.

Why does the `ChromePdfRenderOptions` not contain a proxy setting?

The `ChromePdfRenderOptions` does not include a proxy setting because proxy configuration is handled via a method parameter in specific `RenderHtmlAsPdf` overloads, maintaining flexibility and controlling HTTP/HTTPS requests efficiently.

What environment variables should be set for system-level proxy configurations?

For system-level proxy configurations, set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables for general outbound traffic routing in environments like Docker or CI/CD pipelines.

How do you ensure internal resources bypass the proxy in IronPDF?

You can set the `NO_PROXY` environment variable to list domains or hostnames that should bypass the proxy, ensuring internal resources like local CSS servers or image CDNs aren't routed through the proxy unnecessarily.

What are the typical issues when rendering PDFs through a proxy in IronPDF, and how can they be resolved?

Typical issues include timeout errors due to latency, SSL interception requiring corporate root CA certificates, and NTLM authentication needing a local forwarding proxy like CNTLM. Solutions vary but generally include adjusting timeouts, installing certificates properly, and ensuring correct proxy credentials formatting.

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.

...

Ready to Get Started?

Nuget Downloads 20,878,335|Version:2026.9just released

Free NuGet Download

Total downloads: 20,878,335

View Licenses

Install with NuGet

Version: 2026.9

PM > Install-Package IronPdf

nuget.org/packages/IronPdf/

In Solution Explorer, right-click References, Manage NuGet Packages
Select Browse and search "IronPdf"
Select the package and install

Download DLL

Version: 2026.9

or download Windows Installer here.

Download and unzip IronPDF to a location such as ~/Libs within your Solution directory
In Visual Studio Solution Explorer, right click References. Select Browse, "IronPdf.dll"

Licenses from $999