Troubleshooting and FAQ
19 Aug 202524 minutes to read
Blink files are missing
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 bin folder of the application from NuGet package location.
Please refer to the below screenshot, ![]() (Or) You can set the runtimes folder path explicitly in BlinkPath property in BlinkConverterSettings class. Ex path: C:\HtmlConversion\HTMl-to-PDF\HTMl-to-PDF\bin\Debug\net7.0\runtimes\win-x64\native\
|
BlinkBinaries access is denied in server
Exception | BlinkBinaries access is denied in server. |
---|---|
Reason | If the BlinkBinaries folder does not have elevated permission for the respective user, then the Blink HTML converter may throw this exception. |
Solution | You can add read/write/execute permission to for the BlinkBinaries folder for the respective user group. |
Blink rendering engine only supported from .NET Framework 4.5
Exception | Blink rendering engine 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 the 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 | The exception may occur in the Linux CentOS/Docker environment due to the Chrome browser unable to launch from sandbox mode in CentOS. | |
Solution | To overcome the exception in the Linux CentOS/Docker environment, provide the execute permission for chrome and chrome-wrapper files inside the BlinkBinaries folder.
Refer to the following screenshot: ![]() ![]() Also, please add the following command line arguments in our converter setting.
|
Failed to launch Base
Exception | Failed to launch Base |
---|---|
Reason | The exception may occur due to missing of required dependent packages. |
Solution | To overcome the exception, you can ensure the required dependency in docker file. |
Failed to launch chromium: Missing required dependent packages
Exception | Failed to launch chromium: Missing required dependent packages |
---|---|
Reason | The required dependencies for the Chromium are not installed on the system. |
Solution | Ensure all required dependencies for the Chromium are installed on the system. This may include additional libraries or packages. |
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 |
To overcome this issue, we have three workaround solutions.
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: To resolve this issue, we recommend copying 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. ![]() Step 3: If manually copying the files doesn't meet your requirements, we recommend applying the following code changes in the .csproj file and updating the publish profile. This will ensure the necessary files are copied automatically during the publishing process. Add the following code snippet to the .pubxml file to apply the necessary configuration.
|
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 is not accessed. |
Solution | To overcome the exception, you can 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 the exception, you can add read, write, and execute permissions for the temporary folder. Refer to the following code sample to set the temp folder.
|
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, then the Blink HTML converter may throw this exception. |
Solution | The Blink HTML converter has support for 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. |
Blink converter may create PDF with blank pages
Issue | Blink converter may create PDF with blank pages. |
---|---|
Reason | When the webpage (HTML) is not available or accessible. |
Solution | Please check the internet connection and the HTML page is available in the mentioned location.
Check the HTML file or URL is rendered properly in 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, you can provide an execute permission for chrome and chrome-wrapper files inside the runtimes/linux/native folder by using the docker command.
![]()
|
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 the slow internet connection or due to the behavior that the conversion completed before the page is loaded completely. |
Solution | To overcome this issue, add suitable delay for the conversion using the AdditionalDelay property of the HTMLConverter.
|
Reason | While converting HTML string to PDF, the resources may be missed due to the invalid Base URL. |
Solution | Overcome this issue by passing the valid base URL (path of the resources) along with the HTML string. |
Blink conversion failed in Azure app service (Windows)
Issue | Blink conversion failed in Azure app service (Windows). “The process was terminated due to an unhandled exception” |
---|---|
Reason | Blink rendering engine uses GDI calls for viewing and rendering the webpages. But Azure app service blocks GDI calls in Azure website environment. As azure website does not have the elevated permission and enough rights, so we could not launch the Chrome headless browser 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 the elevated permission and rights to access the GDI calls). Refer to this link for more information. |
HTML to PDF Conversion Fails on Azure App Service When Published via GitHub Actions Using CEF Rendering Engine
Issue | When publishing an application using Syncfusion.HtmlToPdfConverter.Cef.Net.Windows to Azure App Service via GitHub Actions, the HTML to PDF conversion fails. This typically results in a runtime error indicating that a required component or dependency could not be found or initialized. |
---|---|
Reason | The failure is due to native binaries for the CEF(Chromium Embedded Framework) rendering engine located in the runtime/win-x64/native directory not being copied correctly to the output directory during the publishing process. This issue is common in CI/CD pipelines like GitHub Actions, causing the application to fail at runtime due to missing native files. |
Solution | To fix this, explicitly include the CEF runtime package in your .csproj file to ensure the necessary binaries are included in the published output. Add the following package reference.
|
Unable to convert unsecured https URL to PDF using Blink
Issue | Unable to convert unsecured https URL to PDF using Blink. |
---|---|
Reason | The issue is happen due to invalid SSL certificate errors in unsecured sites. |
Solution | You can able to bypass the invalid SSL certificate errors using the command line arguments property of Blink converter settings.
|
Conversion failure in windows server 2012 R2
Issue | Conversion failure in windows server 2012 R2. |
---|---|
Reason | The issue may happen due to windows server environment permission restriction. |
Solution | We can resolve this permission related failure in the Blink rendering engine using below command line arguments in our converter settings.
|
Converting the HTML to PDF fails in x32 bit windows system environment
Exception | Converting the HTML to PDF fails in x32 bit windows system environment. |
---|---|
Reason | The existing x64 bit Blink binaries windows are not compatible with x32 bit windows system architecture. |
Solution | To overcome this issue, we can 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. |
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 | The issue happened because the Windows Server Essentials Media Pack was missing in the Windows server 2012 R2. |
Solution | We can resolve this issue 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 option. 3. Select the Role-based or feature-based installation option and click next. 4. In the left side menu, select server roles, then Windows Server Essentials Experience in the server roles and then click next. 5. Now, 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. |
How to Exclude BlinkBinaries or Runtime Files in Build or Deployment
The runtime files, or blink binaries, will be copied into a bin or published folder while building and publishing the application.
By including the
Note:
Using this approach, you can reduce the deployment size on your own servers.
Refer to the following package reference:
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 in 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 x64 ARM Mac M1 system architecture with Linux Docker. |
Solution |
To resolve this issue, we can install the chromium using the docker file and set the Blink Path to the location where chromium is installed.
Docker File:
|
Background color missing issue in HTML Header and Footer
Exception | Background color missing issue in HTML Header and Footer. |
---|---|
Reason | We do not have the support for adding a custom CSS style in the HTML header and footer. |
Solution |
To resolve this issue, we can add inline styles in element. However, we have attached the sample and output documents for your reference.
|
Zombie process are not closed by default from chrome headless in Linux platform
The zombie process are not closed by default from chrome headless in Linux. However, We can resolve the zombie process issue by using the below command line arguments in converter settings.
//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 | The reported issue occurs due to missing of required Linux dependencies in Azure function to perform the conversion in premium plans (such as Ep1) |
Solution |
To overcome this issue by installing the Linux dependencies package in SSH window. Please refer the below commands and screenshot,
Please refer to the below screenshot, ![]() (Or) We can install the required dependencies using the dependencies vis shell script. Please find the below. ![]() code snippet:
|
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 | The reported 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 below thread for more information, https://support.google.com/chrome/thread/185534985 Blink binaries (Version 109.0.5414.75), https://www.syncfusion.com/downloads/support/directtrac/general/ze/BlinkBinaries_109.0.5414.7560606898 |
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 | The reported issue occurs due to the document or file not being properly disposed or closed, leading to conflicts when attempting to access it again. |
Solution |
We can resolve the reported issue by using the FileStream within the "using" block.
|
HTML to PDF Performance Benchmarks:
We have prepared the following benchmark details for converting HTML to PDF, using the specified machine configuration and input HTML files:
Environment Details:
OS Edition : Windows 11 Enterprise
Version : 22H2
Processor : 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz 2.42 GHz
Installed RAM : 20.0 GB (19.7 GB usable)
System type : 64-bit operating system, x64-based processor
Example Application:
The benchmark details were obtained using the Syncfusion.HtmlToPdfConverter.Net.Windows package. You can refer to the following sample, as well as the input and output files used:
Input HTML files : https://github.com/SyncfusionExamples/html_to_pdf_conversion/tree/main/Performance_Testing/Syncfusion_HTMLtoPDF/wwwroot/Data
Output PDF files : https://www.syncfusion.com/downloads/support/directtrac/general/ze/Output-924807763.zip
Results:
Input Page count | Conversion time (Avg value of 5 conversions) | Process Memory and CPU usage |
---|---|---|
10+ Pages | 2.78 seconds | Memory usage: 318 MB CPU usage: 10% |
100+ pages | 3.65 seconds | Memory usage: 367 MB CPU usage: 14% |
1000+ pages | 6.72 seconds | Memory usage: 813 MB CPU usage: 27% |
10 documents with 100+ pages in a loop | 30.52 seconds | Memory usage: 663 MB CPU usage: 15% |
10 documents with 1000+ pages in a loop | 1 minute 10 seconds | Memory usage: 2.2 GB CPU usage: 64% |
NOTE
The performance metrics were recorded on a freshly configured machine. Speed and memory usage may vary if the machine is running other processes. Additionally, performance can be affected by:
NOTE
- External resources loaded in the HTML (such as images, scripts, and styles)
- Network speed for online URL conversions
- Hardware resources (CPU and memory)
You can download a complete working sample from GitHub.
Custom fonts are not rendered in Azure App Service and Function Linux using Blink.
Issue | Custom fonts are not rendered in Azure App Service and Function Linux using Blink. |
---|---|
Reason | We are internally using the Blink rendering engine to convert HTML to PDF document. Due to the sandbox GDI limitation on Azure App services and Function, custom fonts are not rendered (system-installed font is used instead) because of sandbox GDI API limitations that present even in VM-based Azure Apps plans. So, that the converter will automatically renders with default font. Refer below link for more information. This is a limitation of Azure cloud environment. https://github.com/projectkudu/kudu/wiki/Azure-Web-App-sandbox |
Solution | we can overcome this issue by using Azure cloud service which has the elevated access permissions. If it is possible to use Azure cloud service API for converting HTML to PDF. Please refer below link for converting HTML to PDF in Azure cloud service. The custom font may work in Azure cloud service/Azure VM, we ensured this by creating simple sample in Azure VM and the font is working properly. If possible, kindly use the Azure cloud service with VM to resolve the reported issue. KB: https://www.syncfusion.com/kb/10258/how-to-convert-html-to-pdf-in-azure-using-blink |
How to prevent the DawnCache and CPUCache folders creation during HTML to PDF conversion using CEF rendering engine.
Issue | How to remove the DawnCache and CPUCache folders during HTML to PDF conversion using CEF rendering engine. |
---|---|
Reason | The DawnCache and CPUCache folders are created in project folder while performing HTML to PDF conversion using CEF rendering engine. |
Solution |
You can add below command-line arguments in Cef converter settings to prevent the DawnCache and CPUCache folders creation.
|
Blink files are missing at /user/local/bin while performing HTML to PDF conversion with docker and docker compose file.
Issue | Blink files are missing at /user/local/bin while performing HTML to PDF conversion with docker and docker compose file. |
---|---|
Reason | The exception may occur while performing HTML to PDF conversion with docker and docker compose file due to a permission-related issues. |
Solution |
To overcome the exception by making the root files as executable. For making the root files as executable, you can find the code snippet below which will be added to your docker file.
Please refer to the below screenshot, ![]() |
Converting HTML to PDF using the Alpine Docker image, it crashes after the first conversion.
Issue | Converting HTML to PDF using the Alpine Docker image, it crashes after the first conversion. |
---|---|
Reason | The issue occurs within Chromium specifically for Alpine. |
Solution |
We can resolve this issue by adding command-line arguments to the Blink converter settings. Please refer to the code snippet below.
|
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 | The reported issue may occur due to missing of crashpad handler configuration in your docker file |
Solution |
You can try the below solution steps to overcome the reported issue 'Failed to launch Base! chrome_crashpad_handler: --database is required',
Step 1: Kindly try the below docker file changes in your sample to resolve the chrome_crashpad_handler issue.
|
HTML to PDF Conversion Does Not Work in Azure App Service (Windows) Using Blink Rendering Engine
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 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. Use CEF Rendering Engine in Azure App Service Windows If you must use Azure App Service on Windows, the CEF rendering engine is a suitable alternative for HTML to PDF conversion. Refer to the following documentation for more details: * Azure App Service (Windows) * Azure Function (Windows) |
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:
|
Azure App Service is user interactable before installing the Blink prerequisites by script file
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.
![]() 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:
![]() This ensures that your script runs to install 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. |
Exception | Failed to convert webpage exception in Azure App Service (Windows) using CEF rendering engine — deployed via Azure DevOps pipeline |
---|---|
Reason | Missing CEF (Chromium Embedded Framework) binaries during Azure pipeline deployment. |
Solution | Add the following package references to your `.csproj` file to ensure CEF binaries are included during Azure DevOps build:
|
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 conversion. Example for setting German culture:
|
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, we can either manually install the necessary Chromium dependencies in the SSH portal or include the runtimes folder (Blink binaries) in the project location.
Prerequisites dependencies:
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
Note: We have option to exclude the default Blink binaries from the installation package. This will reduce the size of your deployment package in azure. Please refer to the code snippet below.
<PackageReference Include="Syncfusion.HtmlToPdfConverter.Net.Linux" Version="25.1.35" >
<ExcludeAssets>native</ExcludeAssets>
</PackageReference>