Troubleshooting and FAQ

23 Jul 202624 minutes to read

Exception Blink files are missing
Reason The exception may occur if the runtimes folder is not copied correctly from the NuGet folder.
Solution Ensure that the runtimes folder is copied properly to the bin folder of the application from the NuGet package location.

Please refer to the screenshot below:

Runtime folder

(Or)

You can set the runtimes folder path explicitly using the BlinkPath property in the BlinkConverterSettings class.

Example path: C:\HtmlConversion\HTMl-to-PDF\HTMl-to-PDF\bin\Debug\net7.0\runtimes\win-x64\native\

  • C#
    • //Initialize the HTML to PDF converter.
HtmlToPdfConverter htmlConverter = new HtmlToPdfConverter();
BlinkConverterSettings blinkConverterSettings = new BlinkConverterSettings();
//Set the Blink binaries path.
blinkConverterSettings.BlinkPath = @"C:/HtmlConversion/BlinkBinaries/";
//Assign the Blink converter settings to HTML converter.
htmlConverter.ConverterSettings = blinkConverterSettings;
//Convert the URL to PDF document.
PdfDocument document = htmlConverter.Convert("https://www.syncfusion.com");

//Save and close the PDF document.
document.Save("Output.pdf");
document.Close(true);

    BlinkBinaries access is denied on the server

    Exception BlinkBinaries access is denied on the server.
    Reason If the BlinkBinaries folder does not have elevated permission for the respective user, the Blink HTML converter may throw this exception.
    Solution You can add read/write/execute permission for the BlinkBinaries folder to the respective user group.
    Exception Blink rendering engine is only supported from .NET Framework 4.5.
    Reason HTML conversion using Blink is only supported from .NET Framework 4.5 or above.
    Solution The application should target .NET Framework 4.5 or above to convert HTML using the Blink rendering engine.

    Failed to launch chromium: Running as root without –no-sandbox is not supported

    Exception Failed to launch chromium: Running as root without --no-sandbox is not supported
    Reason This exception may occur in the Linux CentOS/Docker environment because the Chrome browser is unable to launch from sandbox mode in CentOS.
    Solution To overcome this exception in the Linux CentOS/Docker environment, provide execute permission for the chrome and chrome-wrapper files inside the BlinkBinaries folder.
    Refer to the following screenshots:
    Blink chrome file permission
    Blink chrome wrapper file permission
    Also, add the following command line arguments in the converter settings.
  • C#
    • //Set command line arguments to run without sandbox.
blinkConverterSettings.CommandLineArguments.Add("--no-sandbox");
blinkConverterSettings.CommandLineArguments.Add("--disable-setuid-sandbox");

    Failed to launch Base

    Exception Failed to launch Base
    Reason This exception may occur due to missing required dependent packages.
    Solution To overcome this exception, ensure the required dependencies are installed in the Docker file.

    Failed to launch chromium: Missing required dependent packages

    Exception Failed to launch chromium: Missing required dependent packages
    Reason The required dependencies for Chromium are not installed on the system.
    Solution Ensure all required dependencies for Chromium are installed on the system. This may include additional libraries or packages. Here's how you can modify your Docker file:
  • DOCKERFILE
    • FROM your-base-image
RUN apt-get update && apt-get install -yq --no-install-recommends \
    libasound2 \
    libatk1.0-0 \
    libc6 \
    libcairo2 \
    libcups2 \
    libdbus-1-3 \
    libexpat1 \
    libfontconfig1 \
    libgcc1 \
    libgconf-2-4 \
    libgdk-pixbuf2.0-0 \
    libglib2.0-0 \
    libgtk-3-0 \
    libnspr4 \
    libpango-1.0-0 \
    libpangext6 \
    libxfixes3 \
    libxi6 \
    libxrandr2 \
    libxrender1 \
    libxss1 \
    libxtst6 \
    libnss3 \
    libgbm1 \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/*

    Application Crash in Syncfusion 29.X.X Due to Missing locales Folder Required by Chromium During HTML Rendering or Conversion

    Exception Application crashes in Syncfusion libraries version 29.2.11 because Chromium fails to find the required `locales` folder in the published output directory, leading to runtime errors when launching HTML rendering or conversion.
    Reason Starting with Syncfusion package version 29.X.X, Chromium was updated to 133.x.x, which now requires the `locales` directory to be present at runtime. However, when publishing a .NET application with the `linux-x64` runtime identifier, only files are copied to the root output folder and the folder structure including `locales` is omitted. As a result, Chromium cannot locate the required `locales` directory, triggering a runtime exception during HTML rendering or conversion.
    Solution There are three workaround solutions to overcome this issue.
    Step 1: Using the Portable Runtime Identifier ensures that the runtime files are copied into the correct folder structure, allowing the conversion process to complete without any issues.
    Step 2: Copy the runtimes folder into the project directory, placing it at the same level as the .csproj file. Additionally, ensure that all files within the runtimes folder have their Copy to Output Directory property set to Copy if newer. Please refer to the screenshot below for guidance.
    Output dictionary path
    Step 3: If manually copying the files does not meet your requirements, apply the following code changes in the .csproj file and update the publish profile. This ensures the necessary files are copied automatically during the publishing process.
    Add the following code snippet to the .pubxml file to apply the necessary configuration.
  • XAML
    • <PropertyGroup>
 <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>
    Add the following code to the .csproj file to ensure the locales folder is copied to the publish directory during the build process.
  • XAML
    • <ItemGroup>
	<None Include="bin\Release\net9.0\runtimes\linux\native\locales\**\*"
		CopyToOutputDirectory="Always"
		Link="runtimes/linux/native/locales/%(RecursiveDir)%(Filename)%(Extension)"/>
</ItemGroup>

    Access is denied in runtimes folders. Runtimes folder requires read/write/execute permission

    Exception Access is denied in runtimes folders. Runtimes folder requires read/write/execute permission
    Reason The exception may occur if the runtimes folder cannot be accessed.
    Solution To overcome this exception, add read, write, and execute permissions for the runtimes folder.

    Access denied for specified temporary folder

    Exception Access denied for specified temporary folder
    Reason The specified temporary folder path might be inaccessible.
    Solution To overcome this exception, add read, write, and execute permissions for the temporary folder. Refer to the following code sample to set the temp folder.

  • C#
    • BlinkConverterSettings settings = new BlinkConverterSettings();
settings.TempPath = "D://MyProject//bin";

    The temporary folder does not have read permission

    Exception The temporary folder does not have read permission
    Reason If the temporary folder does not have elevated permission for the respective user, the Blink HTML converter may throw this exception.
    Solution The Blink HTML converter supports setting the temporary path. Using the TempPath property, you can set any folder path that has read/write/execute permission. Then, the converter uses this path for creating temporary files.
    Issue Blink converter may create PDF with blank pages.
    Reason The webpage (HTML) is not available or accessible.
    Solution Check the internet connection and ensure the HTML page is available at the specified location.

    Also, verify that the HTML file or URL is rendered properly in the Chrome browser's print preview.

    Failed to launch chromium: Due to insufficient permission unable to launch the chromium process for conversion

    Exception Failed to launch chromium: Due to insufficient permission unable to launch chromium process for conversion.
    Reason This exception might arise because the Blink binary files lack sufficient permissions to be launched from the specified BlinkPath location.
    Solution To overcome this exception, provide execute permission for the chrome and chrome-wrapper files inside the runtimes/linux/native folder using the Docker command.

    ExcludeAssets

  • DOCKERFILE
    • RUN chmod +x /app/runtimes/linux/native/chrome && \
    chmod +x /app/runtimes/linux/native/chrome-wrapper

    Images or other contents in the HTML are missing in the resultant PDF document

    Issue Images or other contents in the HTML are missing in the resultant PDF document.
    Reason The issue may be due to a slow internet connection, or because the conversion completed before the page was loaded completely.
    Solution To overcome this issue, add a suitable delay for the conversion using the AdditionalDelay property of the HTMLConverter.

  • C#
    • BlinkConverterSettings settings = new BlinkConverterSettings();
settings.AdditionalDelay = 4000;
    Reason While converting an HTML string to PDF, the resources may be missed due to an invalid base URL.
    Solution Overcome this issue by passing a valid base URL (path of the resources) along with the HTML string.
    Issue Blink conversion failed in Azure app service (Windows). "The process was terminated due to an unhandled exception"
    Reason The Blink rendering engine uses GDI calls for viewing and rendering webpages. However, Azure app service blocks GDI calls in the Azure website environment. Since the Azure website does not have elevated permissions or sufficient rights, the Chrome headless browser cannot be launched in Azure app service (Azure website and Azure function).
    Solution You can convert HTML to PDF using the Blink rendering engine in Azure cloud service, which has elevated permissions and rights to access GDI calls. Refer to this link for more information.

    HTML to PDF conversion fails after deploying to Azure Function Linux Flex Consumption Plan

    Issue HTML to PDF conversion fails after deploying to Azure Function Linux Flex Consumption Plan
    Reason The Syncfusion HTML-to-PDF converter internally uses the Blink rendering engine, which relies on a headless Chromium browser to render HTML content. On Linux environments, Chromium requires several native dependencies to launch successfully.
    In the Azure Function Linux Flex Consumption Plan, these dependencies cannot be installed due to the following limitations: * No SSH access to manually install packages.
    * Shell script installation attempts fail due to permission restrictions, even when permissions are explicitly set.
    As a result, the Blink-based converter cannot initialize Chromium, leading to failure in HTML-to-PDF conversion.
    Solution To enable HTML-to-PDF conversion using Blink in Azure Functions:
    * Do not use the Flex Consumption Plan for Linux-based Azure Functions.
    * Instead, use one of the following:
    1.Premium Plan
    2.Standard Consumption Plan
    These plans provide the necessary environment and permissions to support Chromium and its dependencies, allowing the Blink engine to function correctly.
    Issue Unable to convert unsecured https URL to PDF using Blink.
    Reason This issue occurs due to invalid SSL certificate errors on unsecured sites.
    Solution You can bypass the invalid SSL certificate errors using the CommandLineArguments property of Blink converter settings.

  • C#
    • BlinkConverterSettings settings = new BlinkConverterSettings();
settings.CommandLineArguments.Add("--ignore-certificate-errors");

    Security Alert - Bundled chrome.exe in HTML-to-PDF Conversion

    Issue Security alerts are triggered when the Syncfusion HTML-to-PDF converter uses a bundled `chrome.exe` executable to render HTML content in headless mode during PDF generation.
    Reason The HTML-to-PDF conversion relies on Chromium's Blink rendering engine:
    1. The NuGet package includes Blink binaries (`chrome.exe`) under `runtimes/win-x64/native`.
    2. This bundled Chrome instance launches in headless mode to render web content.
    3. Security systems flag the execution of embedded binaries as potential risks.
    Solution Use system-installed Chromium instead of the bundled binaries:

    Step 1: Configure the Blink Path
  • C#
    • HtmlToPdfConverter htmlConverter = new HtmlToPdfConverter();
BlinkConverterSettings settings = new BlinkConverterSettings();

// Point to system-installed Chrome.
settings.BlinkPath = @"C:\Program Files\Google\Chrome\Application"; 

//Convert HTML to PDF.
htmlConverter.ConverterSettings = settings;
PdfDocument document = htmlConverter.Convert("https://example.com");

//Save and close the document. 
document.Save("Output.pdf");
document.Close(true);
    Step 2: Verify Installation
    Ensure Chrome exists at the specified path (standard locations): `C:\Program Files\Google\Chrome\Application`

    Conversion failure in Windows Server 2012 R2

    Issue Conversion failure in Windows Server 2012 R2.
    Reason The issue may occur due to Windows Server environment permission restrictions.
    Solution This permission-related failure in the Blink rendering engine can be resolved using the following command line arguments in the converter settings.

  • C#
    • //Set command line arguments to run without sandbox.
blinkConverterSettings.CommandLineArguments.Add("--no-sandbox");
blinkConverterSettings.CommandLineArguments.Add("--disable-setuid-sandbox");

    Converting HTML to PDF fails in x32 bit Windows system environment

    Exception Converting HTML to PDF fails in x32 bit Windows system environment.
    Reason The existing x64 bit Blink binaries for Windows are not compatible with the x32 bit Windows system architecture.
    Solution To overcome this issue, use the x32 bit Blink binaries. The x32 bit Windows Blink binaries are compatible with the x32 bit Windows system environment. Please download the x32 bit Blink binaries for Windows here and replace these binaries in the existing x64 bit Blink binaries folder.
    Issue Hyperlink appearances do not navigate to their referenced URLs when using `CreateTemplate` and `DrawPdfTemplate` methods
    Reason The CreateTemplate and DrawPdfTemplate methods generally do not import annotation details, including hyperlink information, from the original PDF document. This means that while the visual appearance of a hyperlink (blue, underlined text) might be preserved, the underlying functionality of navigating to the URL is not transferred.
    Solution A workaround involves manually extracting and re-applying hyperlink annotations. This can be achieved by following these steps:
    1. Extract Annotations: Before creating and drawing the PDF template, extract all annotations, specifically hyperlink annotations, from the original PDF document.
    2. Draw PDF Template: Use the CreateTemplate and DrawPdfTemplate methods to draw the PDF content into a new document.
    3. Incorporate Annotations: After the template has been drawn, programmatically add the extracted hyperlink annotations to the corresponding positions in the new document. This will restore the interactive functionality of the hyperlinks.
    Please refer to the sample project: HTML-to-PDF-Hyperlink

    ERROR: The specified module could not be found in Windows Server 2012 R2

    Exception The specified module could not be found in Windows Server 2012 R2.
    Reason This issue occurs because the Windows Server Essentials Media Pack is missing on Windows Server 2012 R2.
    Solution This issue can be resolved by installing the Windows Server Essentials Media Pack. To install the Windows Server Essentials Media Pack, first install the Windows Server Essentials.
    1.Open the Server Manager in the Taskbar.
    2.Click Manage in the Server Manager and select Add Roles and Features.
    3.Select the Role-based or feature-based installation option and click Next.
    4.In the left side menu, select Server Roles, then enable Windows Server Essentials Experience, and click Next.
    5.The Windows Server Essentials will be installed.
    6.After successful installation, install the Windows Server Essentials Media Pack.
    Go to the official website to download and install the Windows Server Essentials Media Pack.

    **Note:** This version is only applicable to Windows Server 2012 R2 Standard.

    HTML conversion support in Azure

    HTML conversion support in Azure
    Azure App Service (Linux) Yes
    Azure Functions (Linux) Yes
    Azure Cloud Service Yes
    Azure App Service with Linux docker Yes

    Failed to convert Webpage exception with Linux Docker on Mac M1 machine

    Exception Failed to convert Webpage exception using Linux Docker in Mac M1 system environment.
    Reason The existing x64-bit Blink binaries for Linux are not compatible with the ARM64 Mac M1 system architecture running Linux Docker.
    Solution To resolve this issue, install Chromium using the Dockerfile and set the Blink Path to the location where Chromium is installed.

    Dockerfile:

  • DOCKERFILE
    • FROM mcr.microsoft.com/dotnet/aspnet:7.0 AS base 
RUN apt-get update && apt-get install -y \ 
libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \ 
libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \ 
libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 \ 
libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \ 
libnss3 libgbm1 chromium 
WORKDIR /app 
EXPOSE 80 
EXPOSE 443
    Code example:
  • C#
    • BlinkConverterSettings settings = new BlinkConverterSettings();  

//To utilize the Blink binaries from the arm64-based chromium installed using the docker file, execute the following command.   

settings.BlinkPath = @"/usr/lib/chromium/chromium";
    Exception Background color missing issue in HTML Header and Footer.
    Reason Adding a custom CSS style in the HTML header and footer is not supported.
    Solution To resolve this issue, add inline styles to the element. The following sample demonstrates the approach.

  • C#
    • using Syncfusion.Drawing;
using Syncfusion.HtmlConverter;
using Syncfusion.Pdf;

HtmlToPdfConverter htmlConverter = new HtmlToPdfConverter();
//Initialize blink converter settings. 
BlinkConverterSettings blinkConverterSettings = new BlinkConverterSettings();
//Set the Blink viewport size.
blinkConverterSettings.ViewPortSize = new Size(1280, 0);
//Set the html margin-top value based on the html header height and margin-top value.
blinkConverterSettings.Margin.Top = 70;
//Set the html margin-bottom value based on the html footer height and margin-bottom value.
blinkConverterSettings.Margin.Bottom = 40;
//Set the custom HTML header to add at the top of each page.
blinkConverterSettings.HtmlHeader = " <div style=\"background-color: blue; -webkit-print-color-adjust: exact; margin-left: 40px; font-size: 10px;\">HTML Header</div>";
//Set the custom HTML footer to add at the bottom of each page.
blinkConverterSettings.HtmlFooter = " <div style=\"background-color: blue; -webkit-print-color-adjust: exact;margin-left: 40px; font-size: 10px;\">HTML Footer</div>";
//Assign Blink converter settings to the HTML converter.
htmlConverter.ConverterSettings = blinkConverterSettings;
//Convert the URL to a PDF document.
PdfDocument document = htmlConverter.Convert("<div>Hello World</div>", string.Empty);

//Save and close a PDF document.
document.Save("Output.pdf");
document.Close(true);
    You can download a complete working sample from GitHub.

    Zombie processes are not closed by default from chrome headless on Linux platform

    Zombie processes are not closed by default from chrome headless in Linux. However, this issue can be resolved by using the following command line arguments in the converter settings.

  • C#
    • //Set command line arguments to run without the sandbox.
settings.CommandLineArguments.Add("--no-sandbox");
settings.CommandLineArguments.Add("--disable-setuid-sandbox");
settings.CommandLineArguments.Add("--no-zygote");
settings.CommandLineArguments.Add("--disable-dev-shm-usage");
settings.CommandLineArguments.Add("--single-process");

    Failed to launch chromium: Missing required dependent packages issue occurs in Azure function Linux with premium plans.

    Exception Failed to launch chromium: Missing required dependent packages issue occurs in Azure function Linux with premium plans.
    Reason This issue occurs due to missing required Linux dependencies in the Azure function to perform the conversion in premium plans (such as EP1).
    Solution To overcome this issue, install the Linux dependencies package using the SSH window. Please refer to the commands and screenshot below:
  • BASH
    • apt-get update && apt-get install -yq --no-install-recommends libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libnss3 libgbm1


    Please refer to the screenshot below:

    Failed to launch chromium logo


    (Or)

    The required dependencies can also be installed using a shell script.

    HTML Conversion Dependencies Logo


    Code example:

  • C#
    • private static void InstallLinuxPackages(FileInfo functionAppDirectory)
{
	if (!RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
	{
		return;
	}
	FileAccessPermissions ExecutableFilePermissions = FileAccessPermissions.UserRead | FileAccessPermissions.UserWrite | FileAccessPermissions.UserExecute |
	FileAccessPermissions.GroupRead | FileAccessPermissions.GroupExecute | FileAccessPermissions.OtherRead | FileAccessPermissions.OtherExecute;
	//Install the dependencies packages for HTML to PDF conversion in Linux
	string shellFilePath = Path.Combine(functionAppDirectory.Directory.Parent.FullName, @"wwwroot/data");
	string tempBlinkDir = Path.GetTempPath();
	string dependenciesPath = Path.Combine(tempBlinkDir, "dependenciesInstall.sh");
	if (!File.Exists(dependenciesPath))
	{
		CopyFilesRecursively(shellFilePath, tempBlinkDir);
		var execPath = Path.Combine(tempBlinkDir, "dependenciesInstall.sh");
		if (File.Exists(execPath))
		{
			var code = Function1.Chmod(execPath, ExecutableFilePermissions);
			if (code != 0)
			{
				throw new Exception("Chmod operation failed");
			}
		}
		Process process = new Process
		{
			StartInfo = new ProcessStartInfo
			{
				FileName = "/bin/bash",
				Arguments = "-c " + execPath,
				CreateNoWindow = true,
				UseShellExecute = false,
			}
		};
		process.Start();
		process.WaitForExit();
	}
}

    Failed to load Chrome DLL exception occurs on Windows 7/8 and Windows Server 2008/2012 machines

    Exception Failed to load Chrome DLL exception occurs on Windows 7/8 and Windows Server 2008/2012 machines.
    Reason This issue occurs due to an unsupported OS platform with the latest binaries.
    Solution If you are using Windows 7/8 or Windows Server 2008/2012, please use Chromium version 109 instead of the newer versions. Chromium has discontinued support for these operating systems, and the last compatible version is 109.

    Please refer to the thread below for more information: Thread
    Blink binaries (Version 109.0.5414.75): Blink Binaries

    There was an error opening this document. This file is already open or in use by another application.

    Issue There was an error opening this document. This file is already open or in use by another application.
    Reason This issue occurs because the document or file is not properly disposed or closed, leading to conflicts when attempting to access it again.
    Solution This issue can be resolved by using the `FileStream` within a `using` block.
  • C#
    • using (FileStream fs = new FileStream("path_to_file", FileMode.Open))
{
// Use the file here
} // File stream is automatically closed and disposed
    Or Dispose of the `FileStream` at the end of the process and ensure that the file or document is not already open in another application.
  • C#
    • PdfDocument document = htmlConverter.Convert(");
FileStream fileStream = new FileStream(baseUrl+ "Bill_PDF_04_16_24.pdf", FileMode.CreateNew, FileAccess.ReadWrite);
//Save and close the PDF document.
document.Save(fileStream);
document.Close(true);
document.Dispose();

fileStream.Dispose();
    Issue Custom fonts are not rendered in Azure App Service and Function Linux using Blink.
    Reason Internally, the Blink rendering engine is used to convert HTML to PDF. Due to the sandbox GDI limitation on Azure App Services and Functions, custom fonts are not rendered (the system-installed font is used instead) because of sandbox GDI API limitations that exist even in VM-based Azure Apps plans. As a result, the converter automatically renders with the default font. Refer to the link below for more information. This is a limitation of the Azure cloud environment. Azure Web App sandbox
    Solution This issue can be overcome by using Azure cloud service, which has elevated access permissions. Use the Azure cloud service API for converting HTML to PDF. Please refer to the link below for converting HTML to PDF in Azure cloud service. The custom font may work in Azure cloud service/Azure VM; this was verified by creating a simple sample in an Azure VM, where the font renders properly. If possible, use the Azure cloud service with a VM to resolve this issue. KB: Convert HTML to PDF in Azure using Blink
    Issue Blink files are missing at /user/local/bin while performing HTML to PDF conversion with Docker and docker-compose file.
    Reason This exception may occur while performing HTML to PDF conversion with Docker and docker-compose file due to permission-related issues.
    Solution To overcome this exception, mark the root files as executable. The following code snippet can be added to your Dockerfile:
  • DOCKERFILE
    • USER root
RUN chmod +x /app/runtimes/linux/native/chrome && \
chmod +x /app/runtimes/linux/native/chrome-wrapper


    Please refer to the screenshot below:

    Runtime folder

    Converting HTML to PDF using the Alpine Docker image crashes after the first conversion.

    Issue Converting HTML to PDF using the Alpine Docker image crashes after the first conversion.
    Reason The issue occurs within Chromium specifically for Alpine.
    Solution This issue can be resolved by adding command-line arguments to the Blink converter settings. Please refer to the code snippet below:
  • C#
    • blinkConverterSettings.CommandLineArguments.Add("--disable-gpu");

    Failed to launch Base! chrome_crashpad_handler: –database is required while performing HTML to PDF conversion with Alpine Docker

    Exception Failed to launch Base! chrome_crashpad_handler: --database is required while performing HTML to PDF conversion with Alpine Docker
    Reason This issue may occur due to missing crashpad handler configuration in the Dockerfile.
    Solution You can try the following solution steps to overcome the issue `'Failed to launch Base! chrome_crashpad_handler: --database is required'`:
    Step 1: Apply the following Dockerfile changes in your sample to resolve the `chrome_crashpad_handler` issue.
  • DOCKERFILE
    • FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
LABEL pipelineName="PDFSearch" \
      pipelineKey="ECUNZKAJ" \
      offeringKey="LUSUYQTB"
  
RUN apk upgrade -U
RUN apk add --no-cache tzdata
RUN apk add --no-cache icu-libs
RUN apk update && \
    apk upgrade && \
    apk add --no-cache \
        openssl
RUN apk update && \
   apk upgrade --available && \
   apk add --update ca-certificates && \
   apk add chromium --update-cache --repository  http://nl.alpinelinux.org/alpine/edge/community \
   rm -rf /var/cache/apk/*
COPY . /app
WORKDIR /app
 
RUN mkdir -p /crashpad && \
    chown -R root:root /crashpad
 
ENV XDG_CONFIG_HOME=/tmp/.chromium
ENV XDG_CACHE_HOME=/tmp/.chromium

ENV CHROME_CRASHPAD_DATABASE=/crashpad
 
ARG dotnet_cli_home_dir=/tmp
 
EXPOSE 5000 7000
ENV ASPNETCORE_URLS=http://*:5000
ENV DOTNET_CLI_HOME=$dotnet_cli_home_dir
WORKDIR /app
COPY . /app
USER guest
ENTRYPOINT ["dotnet", "Ops.PDFSearch.Web.dll"]
    A modified Dockerfile is available for your reference: Docker file.
    Step 2: From Chromium version 128.x.x.x.x, the `--database` flag is required for the Chrome crashpad handler. This may cause the issue on your end. Try the steps below to resolve the issue.
    Add the following commands in the Dockerfile:
  • DOCKERFILE
    • RUN mkdir -p /var/www/.config/google-chrome/Crashpad
RUN chown -R www-data:www-data /var/www/.config
    Add the following command-line arguments in the conversion code:
  • C#
    • if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
{
    strLogs.Append("\nPDF: BlinkConverterSettings  for Linux updated BlinkPath to chromium " + GetCurrentTime());
    settings.BlinkPath = "/usr/lib/chromium";
    settings.CommandLineArguments.Add("--no-sandbox");
    settings.CommandLineArguments.Add("--disable-setuid-sandbox");
    settings.CommandLineArguments.Add("--disable-crash-reporter");
    settings.CommandLineArguments.Add("--no-crashpad");
    settings.CommandLineArguments.Add("--disable-dev-shm-usage");
}
    Please refer to the Chromium forum link for more information about this issue.
    Issue HTML to PDF Conversion Does Not Work in Azure App Service (Windows) Using Blink Rendering Engine
    Reason The Blink rendering engine is not supported for HTML to PDF conversion in Azure App Service (Windows) due to the GDI limitations and restrictions inherent in the Azure App Service environment.
    Solution Use the Blink Rendering Engine in Azure App Service Linux or Azure Functions Linux
    To perform HTML to PDF conversion using the Blink rendering engine, you can use the following alternatives:
    *Azure App Service (Linux): The Blink rendering engine is compatible with Azure App Service running on Linux.
    *Azure Functions (Linux): Linux-based Azure Functions can also utilize the Blink rendering engine for successful conversions.
    *Azure App Service (Linux Docker): Deploying the application in a Linux-based Docker container offers another way to use Blink.

    Failed to launch chromium: Missing required dependent packages issue occurs in Azure App Service (Linux)

    Issue Failed to launch chromium: Missing required dependent packages issue occurs in Azure App Service (Linux)
    Reason This issue may occur due to one of the following reasons:
    1.Missing required Linux dependencies
    2.Missing Chromium dependency files
    3.Lack of access permissions for the `chrome` and `chrome-wrapper` files
    Solution To resolve the issue and ensure successful HTML to PDF conversion in Azure App Service (Linux), follow these steps:
    1: Grant File Access Permissions
    Provide read, write, and execute permissions for the `chrome` and `chrome-wrapper` files located in the `runtimes/linux/native` directory. Use the following commands:
  • BASH
    • chmod +rwx   chrome-wrapper
chmod +rwx  chrome
    2: Verify Chrome Dependency Packages
    Check if the necessary dependencies for Chromium are installed by running the following command in the `runtimes/linux/native` directory:
  • BASH
    • ldd chrome
    3: Install Required Dependencies
    You can also perform HTML to PDF conversion in Azure App Service (Linux) by installing the required dependencies directly through the SSH terminal. Use the following command:
  • BASH
    • apt-get update && apt-get install -yq --no-install-recommends  libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libnss3 libgbm1
    For more details on installing the dependencies through the SSH terminal window, refer to the documentation: Convert HTML to PDF in Azure App Service on Linux | Syncfusion
    Issue Azure App Service is user interactable before installing the Blink prerequisites by script file
    Reason User Interaction: The App service might start before installing the required prerequisites, causing user interaction.
    Solution 1.Script Execution at Startup
    Copy the prerequisites script (`dependenciesInstall.sh`) into your application directory.
    Ensure it is configured to always be copied to the output directory during build/publish.
    Runtime folder
    2.Deploy to Azure App Service (Linux)
    Publish your application to the Azure App Service.
    3.Configure Startup Command
    After deployment, go to the Azure portal configuration for your app service.
    In the Startup Command section, add:
  • BASH
    • /home/site/wwwroot/dependenciesInstall.sh && dotnet YourApplicationName.dll

    Runtime folder
    This ensures that your script runs to install the necessary dependencies before the application launches.
    4.Restart the App Service
    This will trigger the execution of your startup script, resolving installation and font issues.
    5.Verification
    After the service restarts, try the conversion or operation again to ensure the issues are resolved.

    Ubuntu 24.04 dependency install fails: libasound2 migrated to libasound2t64; libgconf-2-4 removed

    Exception Installing dependencies on Ubuntu 24.04 fails when attempting to install libasound2 and libgconf-2-4, leading to build/launch errors
    Reason Time64 transition: Ubuntu 24.04 adopted 64-bit timestamp support, renaming several libraries with the t64 suffix. `libasound2` is now a virtual package provided by `libasound2t64`, so installing `libasound2` directly fails. Deprecated removal: `libgconf-2-4` was deprecated and removed starting with Ubuntu 23.10 and is not available in 24.04 repositories.
    Solution Update the dependency installation script to use t64 packages and omit `libgconf-2-4`. The following command installs the supported libraries on Ubuntu 24.04:
  • BASH
    • Run apt-get update && apt-get install -yq --no-install-recommends \
  libasound2t64 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 \
  libfontconfig1 libgcc-s1 libgdk-pixbuf2.0-0 libglib2.0-0t64 libgtk-3-0t64 \
  libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 \
  libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 \
  libxrender1 libxss1 libxtst6 libnss3 libgbm1
    After applying this change, all required dependencies are installed successfully.

    Localized Content Not Reflected in PDF Output When Using Blink HTML-to-PDF Conversion Despite Browser Culture Change

    Exception The output PDF does not display the expected localized (e.g., German) content when converting HTML with the Blink rendering engine, even if the web app's culture is changed in the browser.
    Reason The HTML to PDF converter launches the Blink rendering engine (Chromium headless browser) internally and converts the content at the specified URL or HTML string. If culture or language selection (such as switching from English to German) is implemented using cookies (e.g., .AspNetCore.Culture), the URL itself does not change; only cookies control the localization. The converter does not automatically read or apply browser cookies set during user interaction, so the correct culture is not applied during rendering, resulting in the default (often English) content in the PDF.
    Solution To ensure that the correct localized or culture-specific content appears in the generated PDF:
    Set the required culture cookie explicitly using the Cookies property in BlinkConverterSettings before starting the conversion.
    Example for setting German culture:
  • C#
    • HtmlToPdfConverter htmlConverter = new HtmlToPdfConverter();
BlinkConverterSettings settings = new BlinkConverterSettings();
// Sets German culture
settings.Cookies.Add(".AspNetCore.Culture", "c%3Dde-DE%7Cuic%3Dde-DE"); 
htmlConverter.ConverterSettings = settings;
PdfDocument doc = htmlConverter.Convert(url);

    Due to insufficient permissions, we are unable to launch the Chromium process for conversion in Azure Function .NET 8.0 with premium plans.

    The problem is limited to Azure Functions with premium plans in .NET 8.0 version. To fix this, manually install the necessary Chromium dependencies in the SSH portal or include the runtimes folder (Blink binaries) in the project location.

    Prerequisites dependencies:

  • BASH
    • apt-get update && apt-get install -yq --no-install-recommends libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libnss3 libgbm1

    NOTE

    You have the option to exclude the default Blink binaries from the installation package. This reduces the size of your deployment package in Azure. Please refer to the code example below.

    <PackageReference Include="Syncfusion.HtmlToPdfConverter.Net.Linux" Version="25.1.35" >
	<ExcludeAssets>native</ExcludeAssets>
</PackageReference>

    How to Exclude BlinkBinaries or Runtime Files in Build or Deployment

    When you build or publish the application, the Syncfusion HTML‑to‑PDF converter automatically copies the Blink runtime files (BlinkBinaries) into the bin or publish output folder. These binaries are required for HTML‑to‑PDF conversion at runtime. However, in certain deployment scenarios—such as reducing the deployment size or using a shared/system‑installed Chromium—you can exclude these files and instead provide the Blink binaries manually on the host machine.

    To exclude BlinkBinaries during the build process, configure your project file depending on whether you are using .NET Core/.NET or .NET Framework.

    Exclude BlinkBinaries in .NET Core

    You can prevent runtime files from being included by restricting the package to compile-only assets using the IncludeAssets tag in the PackageReference. This stops all Blink runtime binaries from being copied into the output folder.

    Refer to the following package reference:

    <ItemGroup>
    <PackageReference Include="Syncfusion.HtmlToPdfConverter.Net.Windows" Version="32.1.21">
        <IncludeAssets>compile;runtime</IncludeAssets>
    </PackageReference>
</ItemGroup>

    By using IncludeAssets=”compile”, only the required compile-time metadata is included, and all runtime dependencies (BlinkBinaries) are excluded from the final build or publish output.

    NOTE

    If you exclude runtime files, you must manually place BlinkBinaries on the server and configure BlinkPath in BlinkConverterSettings for conversion to work.

    Exclude BlinkBinaries in .NET Framework Projects

    For .NET Framework applications, Blink runtime files are included through a .targets file referenced in the project.
    To exclude BlinkBinaries, remove this import entry.

    <Import Project="packages\Syncfusion.HtmlToPdfConverter.AspNet.Mvc5.32.1.20\build\net462\Syncfusion.HtmlToPdfConverter.AspNet.Mvc5.targets" Condition="Exists('packages\Syncfusion.HtmlToPdfConverter.AspNet.Mvc5.32.1.20\build\net462\Syncfusion.HtmlToPdfConverter.AspNet.Mvc5.targets')" />

    Removing this line prevents the Syncfusion® build targets from copying BlinkBinaries and other runtime files into your bin folder during build or publish.

    NOTE

    By excluding BlinkBinaries, you can significantly reduce the size of your deployment package, especially in server environments where disk usage and deployment time matter.