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, and an engine that doesn't start at all on Native Library / Runtime Errors.

Read the Reason of a FilterException

When a text filter can't convert a document to or from a format, ServerTextControl.Load and Save throw a FilterException. Its message contains an error number in parentheses, and its Reason property names the cause as a value of FilterException.FilterError. Log both:

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 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 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.

Pass the value that matches the data: a value of StreamType for a file, of BinaryStreamType for a byte array and of StringStreamType for a string.
BinaryStreamType has no value for HTML or RTF. Load these formats from a string or a file.
StreamType.AdobePDFA and StreamType.CascadingStylesheet are for saving only. To load a PDF document, use StreamType.AdobePDF.

Load a Document 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 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 when it's loaded. Ask the user for the password and load the document again, as 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 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.

Check Text after loading, and skip or report documents in which it's empty, as the sample in PDF Conversion does.
Run scanned documents through OCR software before you import them.
To read text together with its position on the page, use PDF.Contents.Lines, as Text Extraction describes.

The TXTextControl Object Must Have Been Completely Loaded

A member of ServerTextControl throws this message:

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

The instance isn't initialized. Create must be called before any other member, and it returns false when the object couldn't be initialized.

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

Create and Dispose Instances shows the code. If Create returns false, see 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 set to false shows the same rectangles.

Set LoadSettings.ImageSearchPath to the folder that holds the images. It replaces the absolute paths in the document. Relative paths are resolved with DocumentBasePath.
Save documents with the image data instead of a reference, as Control How Images Are Saved describes.
Before you deploy templates, check Image.FileName of every image for files that don't exist. The blog article 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, or its merge blocks are missing.

By default, fields of other applications aren't imported as application fields: the default of LoadSettings.ApplicationFieldFormat 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.

Set ApplicationFieldFormat to MSWord, or to MSWordTXFormFields to import form fields as TX Text Control form fields.
For merge blocks, set LoadSettings.LoadSubTextParts to true. It works for DOCX, DOC and RTF documents.

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.

Convert the documents to DOCX where you can.
If DOC is required, use the Classic engine on Windows. 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.

Check the list in What Changes When Converting for the formats you convert between.
If text looks different, see Fonts.
Tables keep their column widths when the page format changes; see Change the Page Format While Converting.

Document Conversion