Customer HUB
Skip to content
English
Go to ironsoftware.com
  • There are no suggestions because the search field is empty.

IronPdfEngine: "Unauthenticated", Exit Code 2 at Start-up or "allow_local_file_access=false" Errors (New Security Settings)

Overview

IronPDF 2026.11.1 adds optional security settings to IronPdfEngine: an access token, a working listen-address setting, and a switch that limits which file paths a request can ask the engine to open. They're all off or unchanged by default, but once one is turned on, a client or start-up command that doesn't match it is rejected. Send the token from the client, pass settings in the supported format, and send HTML content instead of file paths.

Environment

  • OS: Linux containers and the local IronPdfEngine executable
  • Hosting: Docker, Kubernetes, cloud container services, self-hosted engine
  • Language/Runtime: .NET, Java, Python and Node.js clients connecting to IronPdfEngine

Version Metadata

  • Version found: 2026.11.1
  • Version resolved: N/A

Cause

  • IRONPDF_ENGINE_AUTH_TOKEN (default: not set): when set, every call must send the header authorization: Bearer <token>, and health checks stay open. The token is accepted only as an environment variable, so it doesn't appear on the command line or in the engine's logs.
  • allow_local_file_access / IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS (default true): when false, a request that asks the engine to render an HTML file by path or a file: URL is refused, and local custom CSS URLs and font file paths are ignored.Scope: this setting applies to file paths and URLs that a request passes to the engine as parameters. It doesn't filter the content of the HTML you send: resources that the HTML references are loaded by the browser engine as usual. Render only HTML from sources you trust, and keep the engine reachable only by your application (private network and access token).
  • host / IRONPDF_ENGINE_HOST (default 0.0.0.0): before 2026.11.1 this setting was ignored, and it's now applied. Inside a container, localhost or 127.0.0.1 makes the engine unreachable from outside the container.

Solution

RPC error Unauthenticated

IronPdfEngine requires an authentication token. Send the header 'authorization: Bearer <token>' (in IronPdf: IronPdfConnectionConfiguration.Metadata).

The same message appears when the token is missing and when it's wrong. In .NET it's thrown from Installation.ConnectToIronPdfHost, before any render.

  1. Recommended: Send the same token the engine was started with..NET: 
    var config = IronPdfConnectionConfiguration.Docker; 
    config.Metadata.Add("Authorization", "Bearer a-long-random-secret"); 
    Installation.ConnectToIronPdfHost(config);

    For other clients, add the gRPC metadata header authorization with the value Bearer <token>.

  2. Check that the token values match exactly. Leading and trailing spaces are ignored on both sides; anything else must be identical.

Engine stops at start-up with exit code 2

  1. If the log shows the line below, remove auth_token= from the command and set the environment variable instead: 
    ERROR: auth_token cannot be given on the command line. Set the IRONPDF_ENGINE_AUTH_TOKEN environment variable instead.
    docker run -d -p 127.0.0.1:33350:33350 \
       -e IRONPDF_ENGINE_AUTH_TOKEN=a-long-random-secret \
       ironsoftwareofficial/ironpdfengine:<version>
  2. If the log shows one of the lines below, fix the local file access value. Accepted values are true/false, 1/0, yes/no and on/off, in any letter case. The first line comes from the environment variable, the second from the command line. 
    ERROR: IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS='<value>' is not a valid value. Use true or false. 
    ERROR: allow_local_file_access='<value>' is not a valid value. Use true or false.

Warning that the host could not be resolved

  1. If the log shows the lines below, use localhost, an IP address of the machine, or a resolvable host name. Until you fix it, the engine listens on every interface. 
    WARNING: host '<value>' could not be resolved (Name or service not known). 
    WARNING: host '<value>' is not 0.0.0.0, localhost, an IP address or a resolvable host name; listening on every interface. In Docker, keep 0.0.0.0 inside the container and limit access when you publish the port (-p 127.0.0.1:33350:33350).

Render error mentioning allow_local_file_access=false

Rendering an HTML file by path is disabled on this IronPdfEngine (allow_local_file_access=false). 
Send the HTML content instead, or use RenderZipFileAsPdf. 
Rendering a file: URI or local path is disabled on this IronPdfEngine (allow_local_file_access=false). 
Render an http or https URL, or send the HTML content instead.
  1. Send the HTML as a string, render a ZIP with RenderZipFileAsPdf, or render an http(s) URL. The .NET client already sends the HTML content for RenderHtmlFileAsPdf, so that call keeps working. IronPDF for Java's renderHtmlFileAsPdf sends a path, so read the file and render the HTML string instead.
  2. If your clients need to render files by path or file: URL on the engine host, set the variable back to true: 
    -e IRONPDF_ENGINE_ALLOW_LOCAL_FILE_ACCESS=true

CSS or fonts missing, or the default font used, with local file access off

  1. This is by design: local custom CSS URLs and font paths are ignored, and the default font is used instead. Serve the assets over http(s), or embed them in the HTML (inline CSS, data URIs, or a ZIP).

Keep the engine private

  1. Publish the port on one address (-p 127.0.0.1:33350:33350) or keep it on a private Docker network, and never expose it to the internet. Turn on the token wherever more than one app or person can reach the engine. Connections are plain gRPC, so use a private network or a proxy that terminates TLS.

References

Copyright © 2026, Iron Software