# Exceptions

> Handle FilterException, LicenseLevelException, TextEditorException, FormulaException and argument exceptions of ServerTextControl and MailMerge in C#.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > API Reference > .NET API > Exceptions
- **3401 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/exceptions/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/exceptions/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/exceptions/llms-full.txt

---

A call to the TX Text Control .NET class library that can't be carried out ends with an exception. Standard .NET exceptions report a wrong argument or a call at the wrong time, and the library's own exception classes report errors of the text engine, the document filters, the license, table formulas and mail merge. The sections below name each exception, what throws it and how your code can react.

### Exceptions at a Glance

| Exception | Namespace | Thrown when |
|---|---|---|
| `ArgumentException`, `ArgumentNullException`, `ArgumentOutOfRangeException` | `System` | A parameter of a method or the value assigned to a property is wrong |
| `InvalidOperationException` | `System` | A method call isn't valid in the current state of the object |
| [TextEditorException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/texteditorexception/llms-full.txt) | `TXTextControl` | An error occurs while text is edited |
| [FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/llms-full.txt) | `TXTextControl` | A document filter can't convert a document to or from a format |
| [LicenseLevelException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/licenselevelexception/llms-full.txt) | `TXTextControl` | A feature isn't part of the licensed product level |
| [FormulaException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/formulaexception/llms-full.txt) | `TXTextControl` | A table formula has an invalid syntax or misses parameters |
| [NumberFormatException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/numberformatexception/llms-full.txt) | `TXTextControl` | A number format for a formula result has an invalid syntax |
| [MergeCanceledException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mergecanceledexception/llms-full.txt) | `TXTextControl.DocumentServer` | A merge was canceled in the `DataRowMerged` event |
| [ParserException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/parserexception/llms-full.txt) and the classes derived from it | `TXTextControl.DocumentServer.Json` | JSON data passed to a merge can't be parsed |

`TextEditorException`, `FilterException` and `LicenseLevelException` were introduced in version 24.0, `FormulaException` and `NumberFormatException` in version 26.0. All of them derive from `System.Exception`.

### Argument Exceptions

The class library throws `ArgumentException`, `ArgumentNullException` or `ArgumentOutOfRangeException` when a method receives a wrong parameter or a property is set to a wrong value. The reference names these cases:

| Member | Throws `ArgumentException` when |
|---|---|
| [HeaderFooterCollection.GetItem](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/headerfootercollection/getitem-method/llms-full.txt) | The requested header or footer doesn't exist in the collection |
| [Condition](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/condition/llms-full.txt) constructors | The comparison value is `null` or empty, isn't an item of the `SelectionFormField` it is compared with, or is a number that is neither a year nor a day of the month |
| [ConditionalInstruction](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/conditionalinstruction/llms-full.txt) constructor, [ConditionalInstruction.Name](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/conditionalinstruction/name-property/llms-full.txt), [ConditionalInstruction.Conditions](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/conditionalinstruction/conditions-property/llms-full.txt), [ConditionalInstruction.Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/conditionalinstruction/instructions-property/llms-full.txt) | The name is `null` or empty or already used in the collection, or the conditions or instructions are `null`, empty or contain `null` |
| [ConditionalInstructionCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/conditionalinstructioncollection/add-method/llms-full.txt) | The name of the added conditional instruction is `null` or already exists |
| [TXBarcodeCore.Text](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/text-property/llms-full.txt), [TXBarcodeCore.UpperTextLength](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/uppertextlength-property/llms-full.txt) | The value isn't valid for the current barcode type |

A few members throw an exception without the reference naming its type: [FrameBase.InsertionMode](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/framebase/insertionmode-property/llms-full.txt) for a combination of [FrameInsertionMode](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/frameinsertionmode/enumeration/llms-full.txt) values that isn't allowed, and [MergeBlockInfo.Apply](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-datasources/mergeblockinfo/apply-method/llms-full.txt) and [MergeBlockInfo.MergeFields](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-datasources/mergeblockinfo/mergefields-property/llms-full.txt) on a `MergeBlockInfo` that wasn't created from an existing subtext part.

A header that may be missing is a typical case. Catch the exception instead of letting it end the request:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("letter.docx", StreamType.WordprocessingML);

    try
    {
        HeaderFooter header = tx.HeadersAndFooters.GetItem(HeaderFooterType.Header);
        Console.WriteLine($"The header has {header.Paragraphs.Count} paragraphs.");
    }
    catch (ArgumentException)
    {
        // The document has no header
        Console.WriteLine("The document has no header.");
    }
}
```

The code works as follows:

- [ServerTextControl.HeadersAndFooters](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/headersandfooters-property/llms-full.txt) returns the headers and footers of the document.
- `GetItem` with [HeaderFooterType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/headerfootertype/enumeration/llms-full.txt) `Header` throws an `ArgumentException` when the document has no header.

### InvalidOperationException

`InvalidOperationException` means that the object isn't in a state in which the call is allowed. The reference doesn't list the members that throw it. When it occurs, check the order of your calls: an instance of [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/llms-full.txt) needs [Create](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/create-method/llms-full.txt) before any other member, as [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/components/servertextcontrol/llms-full.txt) explains.

### TextEditorException

[TextEditorException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/texteditorexception/llms-full.txt) reports an error of the text engine while a document is edited. With the Core engine, creating the first `ServerTextControl` throws it with the message "The default font installation failed." when the *Fonts* folder of the package is missing next to the application. [The Default Font Installation Failed](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/fonts/#the-default-font-installation-failed) shows the fix.

### FilterException

[FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/llms-full.txt) is thrown when a document filter can't load, save or convert a document, for example by [ServerTextControl.Load](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/load-method/llms-full.txt) and [ServerTextControl.Save](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/save-method/llms-full.txt). Its [FilterException.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):

| Reasons | What they mean |
|---|---|
| `WrongFileType`, `Unsupported`, `Obsolete` | The format or its version isn't supported, or the filter is obsolete |
| `BadToken`, `NotWellFormed`, `FileTooBig` | The file contains a logical error or syntax that isn't well-formed, or it is too big |
| `CannotOpen`, `CannotRead`, `CannotWrite` | The file can't be opened, read or written |
| `Encrypted`, `InvalidPassword` | The encryption scheme isn't supported, or the user password is missing or wrong |
| `NonEmbeddableFont` | The document can't be saved because it uses a font that can't be embedded |
| `InvalidCertificate`, `InvalidTimeServer` | The signing certificate is invalid or has no private key, or the time server doesn't exist or returns invalid data |
| `OutOfMemory`, `Internal` | Memory couldn't be allocated, or an unspecified internal error occurred |

Filter the exception by its reason to handle the cases your application can resolve, such as a PDF document that needs a password:

```csharp
using TXTextControl;

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

    try
    {
        tx.Load("statement.pdf", StreamType.AdobePDF);
    }
    catch (FilterException exception) when (exception.Reason == FilterException.FilterError.InvalidPassword)
    {
        // Ask the user for the password and load the document again
        Console.WriteLine("The PDF document is protected with a password.");
    }
    catch (FilterException exception)
    {
        Console.WriteLine($"The document can't be loaded: {exception.Reason}");
    }
}
```

The code works as follows:

- The first `catch` block handles only the reason `InvalidPassword`; [Load Password-Protected PDF Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/#load-password-protected-pdf-documents) shows how to load the document with its password.
- The second `catch` block handles every other reason.

The message of a `FilterException` also contains an error number, which gives more detail than the reason. Text Control's Error Navigator looks it up, as the blog article [Text Control Error Navigator Launched](https://www.textcontrol.com/blog/2022/08/15/text-control-error-navigator-launched/) explains. [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/conversion/#read-the-reason-of-a-filterexception) in Troubleshooting covers the common conversion problems.

### LicenseLevelException

[LicenseLevelException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/licenselevelexception/llms-full.txt) is thrown when code uses a feature that the licensed product level doesn't include. Its message names the level the feature requires. [A Feature Throws LicenseLevelException](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/licensing/#a-feature-throws-licenselevelexception) lists the messages and shows how to read the product level with [GetVersionInfo](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/getversioninfo-method/llms-full.txt).

### FormulaException and NumberFormatException

Both exceptions report an error in a string of a table:

- [FormulaException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/formulaexception/llms-full.txt) reports an invalid syntax or missing parameters in a formula, the value of [TableCell.Formula](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/tablecell/formula-property/llms-full.txt).
- [NumberFormatException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/numberformatexception/llms-full.txt) reports an invalid syntax in a number format that displays a formula result, the value of [TableCellFormat.NumberFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/tablecellformat/numberformat-property/llms-full.txt).

Both have a `CharacterIndex` property, [FormulaException.CharacterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/formulaexception/characterindex-property/llms-full.txt) and [NumberFormatException.CharacterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/numberformatexception/characterindex-property/llms-full.txt), with the one-based index of the first invalid character in the string. Use it to point the user at the error. [Tables](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/tables/llms-full.txt) shows how formulas and number formats are set, and [Formula Functions](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/formula-functions/llms-full.txt) lists the functions a formula can call.

### Mail Merge Exceptions

[MailMerge.Merge](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/merge-method/llms-full.txt) throws [MergeCanceledException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mergecanceledexception/llms-full.txt) when a handler of the `DataRowMerged` event has set [DataRowMergedEventArgs.Cancel](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-datarowmergedeventargs/cancel-property/llms-full.txt) to cancel the merge.

[MailMerge.MergeJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/mergejsondata-method/llms-full.txt) throws a class derived from [ParserException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/parserexception/llms-full.txt) when the JSON string can't be parsed: [UnexpectedEndOfInputException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/unexpectedendofinputexception/llms-full.txt), [UnexpectedTokenException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/unexpectedtokenexception/llms-full.txt), [InvalidNumberFormatException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/invalidnumberformatexception/llms-full.txt), [InvalidCodePointException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/invalidcodepointexception/llms-full.txt), [UnknownLiteralNameTokenException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/unknownliteralnametokenexception/llms-full.txt) or [UnknownParseErrorException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-json/unknownparseerrorexception/llms-full.txt). Catch `ParserException` to handle all of them; [Data Sources](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/data-sources/llms-full.txt) shows the code.

### Related Pages

- [Classes by Task](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/tasks/llms-full.txt): the classes of the library sorted by task.
- [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/conversion/llms-full.txt): the reasons of a `FilterException` and their fixes.
- [Licensing](https://docs.textcontrol.com/tx-text-control-dotnet-server/troubleshooting/licensing/llms-full.txt): license errors and `LicenseLevelException`.
- [REST Services](https://docs.textcontrol.com/tx-text-control-dotnet-server/integration/rest-services/llms-full.txt): turn exceptions into HTTP status codes.

---

## Nearby

- **Previous:** [Classes by Task](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/tasks/llms-full.txt)
- **Next:** [TXTextControl.AI](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/txtextcontrol-ai/llms-full.txt)