Skip to main content

Convert Microsoft Office files

The Conversion Service uses Microsoft Office applications to process jobs containing Word, Excel, and PowerPoint documents. Select one of the following two options when configuring the Microsoft Office file conversion in the Conversion Service Configurator:

These options differ in configuration parameters, output quality, and performance. Both options extract embedded documents from Office documents in Open XML format (for example, DOCX, XLSX, PPTX) in a destructuring step before conversion. Macro instructions are disabled in all cases.

Choose a Microsoft Office conversion method

To ensure high-quality conversion with accurate layout and visual fidelity, the Conversion Service offers two Microsoft-based processing options: a local Microsoft Office installation or the Office for the web service in Microsoft Azure Cloud. Both options deliver equally high conversion quality, with no significant differences identified in detailed comparisons.

Use the local Microsoft Office installation if you:

  • Require high performance. Cloud conversion may involve significant overhead for uploading and downloading file contents.
  • Need to convert large documents (more than 100 MB).
  • Want to process many large Excel files.
    • Only the local installation option supports fit to page in Microsoft Excel.
    • Microsoft Excel files with many sheets or hundreds of pages aren't supported in the Office for the web service.
  • Must repair Word documents.
  • Work with password-protected documents.
  • Handle macro-enabled files (XLTM, PPTM, WordML).
  • Need to use special or custom fonts.
    • Fonts can be installed locally but not added to the web service.
    • The web service includes more default fonts than a typical Windows server.
  • Keep data on-premises if required by security policies or if you require a lack of internet access.
    • Web service conversions temporarily store files in the Azure cloud. Storage region depends on your subscription.

Use the Convert using the Office for the web service if:

  • You're converting smaller files (smaller than 100 MB), especially Word documents.
  • Files were created using Microsoft Office for the web.
  • You're deploying the Docker version in production.
  • You prefer lower setup and maintenance overhead.

Convert files using local Microsoft Office installation

caution

To comply with Microsoft licensing, each client submitting Word, Excel, or PowerPoint jobs must be licensed for Microsoft Office. For more information, see Licensing Microsoft Office software in Commercial Licensing on the Microsoft site.

If you want to Convert files using local Microsoft Office installation, you must have a compatible version of Microsoft Office installed on the Conversion Service server:

Office version
Office 2019* (64-bit)
Office 2021 (64-bit)
Office 2024 (64-bit)
Microsoft 365 (64-bit)

* The Pdftools support for Microsoft Office 2019 will end in October 2025.

The supported language is English (United States). The Microsoft Print to PDF virtual printer must also be installed.

Microsoft Office version compatibility

For optimal conversion results, use the same Microsoft Office version that was used to create the documents. The Conversion Service only supports Microsoft Office 2019 and later.

Install and configure local Microsoft Office installation

During Microsoft Office setup, follow these steps and requirements:

  1. Use a static license key (device-based license), especially with Microsoft 365. Avoid user logins to prevent dialog pop-ups that can interrupt processing.
  2. After installation, activate the Office license.
  3. Open sample Word, Excel, and PowerPoint files to confirm there are no blocking pop-ups.
  4. If your documents rely on language features like hyphenation, install the required language packs.
Improve performance with Windows Defender exceptions

If Windows Defender is active, enabling the Windows Defender Rules setting in the Configurator may improve conversion speed. It adds exceptions for specific processes and folders to reduce scanning overhead.

Enable it under Conversion Service > Windows Defender Rules. Windows Defender in Configurator

Make sure group policies don't override these exceptions.

Third-party antivirus software

Third-party tools like Bitdefender may block required operations. To guarantee successful conversion, you must add any application exceptions to your third-party antivirus software.

Set up on Windows

Assign a user account for the local Microsoft Office installation. You can either:

  • Recommended: Use automatically generated user account
  • Existing user account

Unless restricted by security policies or domain controllers, let the Conversion Service Configurator create a ConvsrvOfficeUser account with a secure password.

The following settings are applied automatically:

  • Joins the Users group.
  • Has encrypted credentials saved through the Windows Data Protection API.
  • Grants the user Allow log on locally and Log on as a batch job security policies.
  • Has registry and DCOM permissions for Word, Excel, and PowerPoint.

To set up an automatically generated user account in the Configurator:

  1. In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
    Screenshot of the general settings in the Configurator's Conversion Service tab.
  2. Next to the Office Conversion, click Configure
  3. Select Local Office Installation and Automatically Create a User Account, and then click Next.
  4. Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
  5. ConvsrvOfficeUser appears in the username field with a random password. Click Apply.
note

The automatically generated user account is recommended for most servers unless specific security policies or domain controller restrictions apply. This is the case if:

Use an existing user account

Use this if your server has strict security rules or is managed through a domain controller.

Requirements:

  • Create the user account manually (local or domain). The Conversion Service Configurator does not modify this account.
  • Grant Allow log on locally and Log on as a batch job (or assign to a group with these rights).
  • Don't assign admin privileges. Set up the user account with minimum user rights (don't assign the user account to the Administrators group).
  • Update the configuration if the password changes or expires.

These properties and settings are set automatically:

  • The password is encrypted using the Windows Data Protection API before it is stored in a configuration file.
  • The registry and DCOM permissions for Word, Excel, and PowerPoint are adjusted.
caution

If using a domain user, disable any group policies enforcing regular password changes. Otherwise, you'll need to reconfigure the Office setup each time the password changes.

To set up an existing user account in the Configurator:

  1. In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
    Screenshot of the general settings in the Configurator's Conversion Service tab.
  2. Next to the Office Conversion, click Configure
  3. Select Local Office Installation with an Existing User Account, and then click Next.
  4. Enter the username and password for the user account. The Conversion Service accepts all standard formats for Windows users (both Username@domain and domain\Username formats). The Username is automatically resolved to ServerName\Username.
  5. Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.

Set up in Docker container

Send Office documents to another Conversion Service instance of the Conversion Service running on Windows. Office document conversion can be activated as follows:

  1. Set up and run the service on Windows.

  2. Enable Office Conversion in the Processing Steps section of your profile. Note that this is active by default.

  3. When starting the Docker container, set the WINDOWS_SERVICE_ENDPOINT environment variable:

    docker run -dp 13033:13033 ... \
    -e WINDOWS_SERVICE_ENDPOINT=http://server:13033/conversion/v1.0/rest \
    pdftoolsag/conversion-service

    Note that if the Windows service uses HTTPS, its host certificate must be trusted by the Docker container. Otherwise, no connection can be established. By default, no trusted certificates are installed.

  4. Copy trusted certificates to /usr/local/share/ca-certificates/.

  5. Run the command update-ca-certificates.

Convert using the Office for the web service

The Office for the web service option converts the documents using a Microsoft Azure Cloud service. Technologies used with this option include the Microsoft Authentication Library (MSAL), the Microsoft Graph API, and the Microsoft Sharepoint API.

The conversion flow:

  1. Upload the file to the user's OneDrive.
  2. Convert the file to PDF.
  3. Delete the uploaded file.

All connections use HTTPS. The service encrypts files before transmitting them over the internet.

caution

You need a valid license to allow the Conversion Service to convert Word, Excel, and PowerPoint documents. This means you must have:

  1. Microsoft 365 for business subscription (Azure Cloud tenant) with a dedicated user account.
  2. Microsoft 365 license for this dedicated user.

You should create a dedicated user account, as full control over this user's OneDrive is requested.

Set up on Windows

Use the Configurator to set up the Office for the web:

  1. In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
    Screenshot of the general settings in the Configurator's Conversion Service tab.
  2. Next to the Office Conversion, click Configure
  3. Select Office for the web, and then click Next.
  4. Enter the user account login (usually, an email address) for the Microsoft Office for the Web Service in the Username field.
  5. Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
  6. Sign in to the Microsoft 365 user account in the pop-up window that appears. Enter the password for the user account. If your company has set up 2-factor authentication, enter the authenticator code and click Verify.

Set up in Docker

  1. Enable Office Conversion in the Processing Steps section of your profile. Note that this option is active by default.
  2. Create a persistent volume (for example, convsrv-etc) to store the authentication token cache.
    docker volume create --name convsrv-etc
  3. Create the token cache directory and set permissions. Mount the volume, create the TokenCaches folder, and give the Conversion Service user read and write access.
    docker run --rm \
    --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
    --user root pdftoolsag/conversion-service \
    bash -c "mkdir /etc/convsrv/TokenCaches && chown convsrv:convsrv /etc/convsrv/TokenCaches"
  4. Initialize the token cache by running the csconfig tool to:
    docker run \
    --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
    -e SERVICE__OFFICE__TYPE=OfficeWebService \
    -e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
    pdftoolsag/conversion-service \
    bash -c "bin/csconfig office webinit"
  5. To start the Docker container, mount the token cache volume and set the required environment variables.
    docker run -dp 13033:13033 \
    --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
    -e SERVICE__OFFICE__TYPE=OfficeWebService \
    -e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
    pdftoolsag/conversion-service
    Set environment variables SERVICE__OFFICE__TYPE and SERVICE__OFFICE__USERNAME according to the configured user and office type.

Troubleshooting

You may encounter problems when setting up and using Office conversion. The issues can be divided into two categories:

Configuration errors

The following sections include the warnings and errors that you encounter inside the Configurator during configuration and possible solutions.

Microsoft Office is not installed
Click to expand for more details and solution:

Office not installed

Solution:
The conversion of Word, Excel, and PowerPoint documents to PDF requires an installation of Microsoft Office on the same server where the Conversion Service is installed. Install a compatible Microsoft Office version (see compatible Microsoft Office versions).

3-Heights Document Converter installation detected
Click to expand for more details and solution:

Office DCB

Solution:
A parallel operation of the Conversion Service and the 3-Heights Document Converter on the same server is not recommended because the Office configurations of the two services interfere and break each other.
User validation failed
Click to expand for more details and solution:

User validation failed

Solution:
This error usually occurs when the user domain is not recognized. Check the spelling and specify the domain by writing the username in SAM or UPN format, for example YourDomain\YourDomainUser or YourDomainUser@YourDomain.com, respectively.
Trust relationship failed
Click to expand for more details and solution:

Trust relationship failed

Solution:
Solution: This error usually indicates a connection issue between the server and the domain controller. Check that the server where the Conversion Service is installed is a member of the domain you are trying to access.
Office configuration problem in Configurator
Click to expand for more details and solution:

Office configuration in Configurator

Solution:
This message can occur when a setting related to the Office Configuration was changed after the Office User was configured. Try to configure the Office user again. If the problem persists or another error occurs, contact Support.
The user name or password is incorrect when using a domain user account
Click to expand for more details and solution:

The Office conversion suddenly stops working when using a domain user account. In this case, the error is usually caused by a password group policy that forces password change at a regular interval. You need to disable the group policy for that domain user.

The following sections include errors that are associated with the Microsoft Office application use.

The document is corrupt or a pop-up dialog window blocks the conversion process
Click to expand for more details and solution:
This error may occur if the document is corrupt or a pop-up blocks the conversion process. It occurs when no progress in the conversion of the Office document was observed for a certain amount of time. If the error was triggered by a pop-up dialog box that is blocking the conversion process, the problem may sometimes be resolved by opening and editing the document manually.
The application WINWORD exceeded the memory limit of 2048 MB
Click to expand for more details and solution:
This error indicates that, during the conversion of a Microsoft Word document (for example DOCX), the application process (Microsoft Word) required more than 2048 MB of memory during conversion. This limit is a precaution set by the Conversion Service to support the overall stability of the conversion process.
For further assistance, contact Support. Include the input file in the support ticket.
Conversion of test.docx to PDF failed COM Exception: (0x80004005)
Click to expand for more details and solution:
If you use Microsoft Windows Defender or another third-party antivirus software, the conversion process for Office may fail, particularly when using Microsoft Excel.

If this is the case, check:

  • Windows Defender Rules are enabled in the Configurator.
  • Any exceptions in the Windows Defender Rules are not forbidden by group policy
  • Any exceptions are added to any third-party antivirus software (for example Bitdefender)
COM Exception: (0x800a18a0): You are attempting to open a file type xxx that has been blocked by your File Block settings in the Trust Center.
Click to expand for more details and solution:
This error occurs when the Trust Center settings block the file. The settings can be adjusted by opening Word (or Excel) as the configured Office User and changing the File Block settings in Office. You need to restart the service after performing this change.
Excel conversion fails with a “Generic” error (COM exception 0x800a03ec)
Click to expand for more details and solution:

This error may be caused by the printer spooler or Microsoft Printer. The printer spooler is required for Office conversion.

If you encounter this error, check: