# Document Conversion

> Solve conversion errors with ServerTextControl: FilterException reasons, wrong StreamType, protected PDFs, PDFs without text, missing images and DOC on Core.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Troubleshooting > Document Conversion
- **2274 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/conversion/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/conversion/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/conversion/llms-full.txt

---

Loading a document, converting it or saving it can fail with a `FilterException`, or it succeeds and the result isn't what you expected. Both kinds follow, starting with the exception and its reason. Text that looks different because a font is missing is covered on [Fonts](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/fonts/llms-full.txt), and an engine that doesn't start at all on [Native Library / Runtime Errors](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/native-libraries/llms-full.txt).

### Read the Reason of a FilterException

When a text filter can't convert a document to or from a format, [ServerTextControl.Load](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/load-method/llms-full.txt) and [Save](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/save-method/llms-full.txt) throw a [FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/llms-full.txt). Its message contains an error number in parentheses, and its [Reason](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/reason-property/llms-full.txt) property names the cause as a value of [FilterException.FilterError](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/filtererror-enumeration/llms-full.txt). Log both:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    try
    {
        tx.Load("contract.docx", StreamType.WordprocessingML);
    }
    catch (FilterException exception)
    {
        // The message contains the error number, Reason the cause
        Console.WriteLine($"{exception.Reason}: {exception.Message}");
    }
}
```

[FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/exceptions/#filterexception) in the .NET API reference lists what each reason means. The error number gives more detail than the reason; Text Control's Error Navigator looks it up, as that section explains.

### The File Type Is Not Supported Through the Filter

Loading fails with a message such as:

```text
Text filter error: The file type is not supported through the filter.
(1-1D01)
```

The reason is `WrongFileType`: the data doesn't have the format that the format value of `Load` names, for example a string of plain text loaded as RTF.

1. Pass the value that matches the data: a value of [StreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/streamtype/enumeration/llms-full.txt) for a file, of [BinaryStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/binarystreamtype/enumeration/llms-full.txt) for a byte array and of [StringStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/stringstreamtype/enumeration/llms-full.txt) for a string.
2. `BinaryStreamType` has no value for HTML or RTF. Load these formats from a string or a file.
3. `StreamType.AdobePDFA` and `StreamType.CascadingStylesheet` are for saving only. To load a PDF document, use `StreamType.AdobePDF`.

[Load a Document](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-processing/load/llms-full.txt) shows which value belongs to which format.

### A Password-Protected PDF Doesn't Load

Loading a PDF document throws a `FilterException` whose `Reason` is `InvalidPassword`:

```text
Text filter error: The specified user-password is invalid.
```

The PDF document is protected with a user password, which has to be passed in [LoadSettings.UserPassword](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/userpassword-property/llms-full.txt) when it's loaded. Ask the user for the password and load the document again, as [Load Password-Protected PDF Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/#load-password-protected-pdf-documents) shows.

If the `Reason` is `Encrypted`, TX Text Control can't import the encryption of the document, for example that of a document encrypted by Acrobat 9.0 or later. The same section lists the encryption schemes the PDF import supports.

### A Loaded PDF Contains No Text

A PDF document loads without an error, but [ServerTextControl.Text](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/text-property/llms-full.txt) is empty.

A PDF document describes what each character looks like and where it is, but not always which character it is. Most PDF documents contain a mapping to the characters, and without it no text can be extracted. A scanned page is an image and contains no text at all.

1. Check `Text` after loading, and skip or report documents in which it's empty, as the sample in [PDF Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/conversion/#convert-pdf-documents-to-editable-formats) does.
2. Run scanned documents through OCR software before you import them.
3. To read text together with its position on the page, use [PDF.Contents.Lines](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-pdf/contents-lines/llms-full.txt), as [Text Extraction](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/text-extraction/llms-full.txt) describes.

### The TXTextControl Object Must Have Been Completely Loaded

A member of `ServerTextControl` throws this message:

```text
The TXTextControl object must have been completely loaded to use this method.
```

The instance isn't initialized. [Create](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/create-method/llms-full.txt) must be called before any other member, and it returns `false` when the object couldn't be initialized.

1. Call `Create` directly after `new ServerTextControl()`, before `Load` or any other member.
2. Check the return value of `Create`, and don't use the instance when it's `false`.
3. Create every instance in a `using` block, so that it's disposed.

[Create and Dispose Instances](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/#create-and-dispose-instances) shows the code. If `Create` returns `false`, see [Create Returns False](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/native-libraries/#create-returns-false).

### Images Are Missing After Loading

Where an image should be, the document shows a rectangle of the image's size with the file name of the image.

An image inserted from a file can be saved as a reference to the file, with its absolute path. When the document is loaded on a server where this path doesn't exist, for example because it pointed to a desktop, a network share or an old folder, the image can't be found. [LoadSettings.LoadImages](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadimages-property/llms-full.txt) set to `false` shows the same rectangles.

1. Set [LoadSettings.ImageSearchPath](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/imagesearchpath-property/llms-full.txt) to the folder that holds the images. It replaces the absolute paths in the document. Relative paths are resolved with [DocumentBasePath](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/documentbasepath-property/llms-full.txt).
2. Save documents with the image data instead of a reference, as [Control How Images Are Saved](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/images/#control-how-images-are-saved) describes.
3. Before you deploy templates, check [Image.FileName](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/image/filename-property/llms-full.txt) of every image for files that don't exist. The blog article [Check TX Text Control Template Dependencies Before Deployment](https://www.textcontrol.com/blog/2026/07/28/check-tx-text-control-template-dependencies-before-deployment/) shows such a check.

### Word Fields Are Missing After Loading

A Word template loads, but its merge fields aren't in [ServerTextControl.ApplicationFields](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/applicationfields-property/llms-full.txt), or its merge blocks are missing.

By default, fields of other applications aren't imported as application fields: the default of [LoadSettings.ApplicationFieldFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/applicationfieldformat-property/llms-full.txt) is `None`. Merge blocks are stored as subtext parts, which are loaded from bookmarks that extend over several characters only when you ask for it.

1. Set `ApplicationFieldFormat` to `MSWord`, or to `MSWordTXFormFields` to import form fields as TX Text Control form fields.
2. For merge blocks, set [LoadSettings.LoadSubTextParts](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadsubtextparts-property/llms-full.txt) to `true`. It works for DOCX, DOC and RTF documents.

[Control the Import With LoadSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/#control-the-import-with-loadsettings) shows both settings.

### A DOC File Can't Be Converted on the Core Engine

The application runs on the Core engine, from the package `TXTextControl.TextControl.Core.SDK`, and has to load or save documents in the Word 97-2003 format (DOC).

The Core engine doesn't import or export DOC. Only the Classic engine, in `TXTextControl.TextControl.ASP.SDK`, supports it, and Classic runs on Windows only.

1. Convert the documents to DOCX where you can.
2. If DOC is required, use the Classic engine on Windows. [Core and Classic Differences](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/file-formats/#core-and-classic-differences) lists the other differences of the formats.

### The Converted Document Looks Different

The document converts without an error, but the result differs from the original: line and page breaks moved, fields or headers are gone, or tables don't fit a new page width.

Every format stores different information, and a conversion keeps only what the target format can hold. HTML, for example, has no pages, so headers, footers and page breaks are lost. Fonts that aren't available on the server are replaced, which changes line and page breaks, and moving from Classic on Windows to Core on Linux changes the available fonts.

1. Check the list in [What Changes When Converting](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/saving-converting/#what-changes-when-converting) for the formats you convert between.
2. If text looks different, see [Fonts](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/fonts/llms-full.txt).
3. Tables keep their column widths when the page format changes; see [Change the Page Format While Converting](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/conversion/#change-the-page-format-while-converting).

### Related Pages

- [Loading Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/llms-full.txt): formats, load settings and error handling.
- [Saving and Converting Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/saving-converting/llms-full.txt): save settings and conversions.
- [Large Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/performance/large-documents/llms-full.txt): request size limits and long-running conversions.
- [Fonts](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/fonts/llms-full.txt): replaced fonts and fonts that can't be embedded in PDF documents.

---

## Nearby

- **Previous:** [Azure](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/azure/llms-full.txt)
- **Next:** [Native Library / Runtime Errors](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/native-libraries/llms-full.txt)