# Exceptions and Error Handling > Handle FilterException, LicenseLevelException and other TX Text Control exceptions in Windows Forms: return values, loading, Task.Run and ThreadException. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Document Processing > Exceptions and Error Handling - **2919 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/exceptions/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/exceptions/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/exceptions/llms-full.txt --- A document that can't be read, a feature your edition doesn't include, a formula with a typo: TX Text Control reports such errors with exceptions of its own, and many of its methods report expected failures through a return value instead. Knowing which is which tells you where a Windows Forms application needs a `try` block, where it checks a result, and what it shows the user. The handlers are in *Form1.cs* with the `TextControl` named `textControl1`. Solutions for specific errors are collected in [Troubleshooting](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/llms-full.txt). ### How TX Text Control Reports Errors TX Text Control uses three ways: - **Its own exception classes** for errors of the document engine, listed in the next section. - **Standard .NET exceptions** for wrong use of the programming interface. An `ArgumentException`, `ArgumentNullException` or `ArgumentOutOfRangeException` is thrown when the parameter of a method or the value of a property is wrong, and an `InvalidOperationException` when a method can't be called in the current state of an object. - **Return values** for results that are expected in normal operation. `Add` methods return `false` or an `AddResult` value when an element can't be inserted at the input position, and [ServerTextControl.Create](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/servertextcontrol/create-method/llms-full.txt) returns `false` when an instance can't be initialized. These cases throw no exception, so check the result. ### TX Text Control Exceptions | Exception | Thrown when | |---|---| | [FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/filterexception/llms-full.txt) | A document can't be converted to or from a format, when it is loaded or saved | | [LicenseLevelException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/licenselevelexception/llms-full.txt) | Your code uses a feature that the licensed edition doesn't include | | [TextEditorException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/texteditorexception/llms-full.txt) | An error occurs while text is edited | | [FormulaException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formulaexception/llms-full.txt) | A table formula has invalid syntax or missing parameters | | [NumberFormatException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/numberformatexception/llms-full.txt) | The number format of a formula result has invalid syntax | | [DocumentServer.MergeCanceledException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mergecanceledexception/llms-full.txt) | A merge was canceled through [DataRowMergedEventArgs.Cancel](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge-datarowmergedeventargs/cancel-property/llms-full.txt) | | [DocumentServer.Json.ParserException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-json/parserexception/llms-full.txt) and its derived classes | [MailMerge.MergeJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergejsondata-method/llms-full.txt) receives invalid JSON | The message of a TX Text Control exception contains an error number in parentheses, such as `(1-1D01)`, which identifies the error more exactly than the text. The blog article [Text Control Error Navigator Launched](https://www.textcontrol.com/blog/2022/08/15/text-control-error-navigator-launched/) shows how to look up these numbers. [FormulaException.CharacterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/formulaexception/characterindex-property/llms-full.txt) and [NumberFormatException.CharacterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/numberformatexception/characterindex-property/llms-full.txt) give the one-based position of the first invalid character. ### Handle Errors When Loading and Saving Loading is where most errors come from, because documents come from outside. [FilterException.Reason](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/filterexception/reason-property/llms-full.txt) tells the cause as a value of [FilterException.FilterError](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/filterexception/filtererror-enumeration/llms-full.txt). The following handler lets the user open a DOCX file and explains what went wrong: ```csharp private void openButton_Click(object sender, EventArgs e) { using (OpenFileDialog dialog = new OpenFileDialog { Filter = "Word documents|*.docx" }) { if (dialog.ShowDialog(this) != DialogResult.OK) { return; } try { textControl1.Load(dialog.FileName, TXTextControl.StreamType.WordprocessingML); } catch (TXTextControl.FilterException exception) { string text = exception.Reason switch { TXTextControl.FilterException.FilterError.WrongFileType => "The file isn't a Word document.", TXTextControl.FilterException.FilterError.Encrypted => "The document is encrypted.", TXTextControl.FilterException.FilterError.CannotOpen => "The file couldn't be opened.", _ => "The document couldn't be loaded." }; MessageBox.Show(this, $"{text}\n\n{exception.Message}", "Open", MessageBoxButtons.OK, MessageBoxIcon.Error); } } } ``` The code works as follows: - [TextControl.Load](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/load-method/llms-full.txt) throws the `FilterException` when the file can't be converted. - The `switch` expression turns three values of `FilterError` into a message for the user; `exception.Message` contains the text and error number of TX Text Control. Other values include `CannotRead`, `FileTooBig`, `Unsupported`, `NotWellFormed` and `InvalidPassword`. - An `IOException` of .NET, such as a file locked by another program, isn't a `FilterException`. Catch it separately when your application opens files the user chooses. [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/llms-full.txt) in Troubleshooting explains each value of `FilterError` and its fix. Saving throws a `FilterException` too, for example with `NonEmbeddableFont` when a PDF can't be created because a font may not be embedded. ### Handle Features of Another Edition A `LicenseLevelException` means that the code uses a feature of an edition that isn't licensed, for example form fields in the Professional edition. It is an error in the application rather than in a document: fix it by using features of your edition, which [Editions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/editions/llms-full.txt) lists, or by licensing another edition. [Licensing](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/licensing/llms-full.txt) in Troubleshooting shows the messages. Where the application can continue without the feature, catch the exception and tell the user: ```csharp private void insertFormFieldButton_Click(object sender, EventArgs e) { try { textControl1.FormFields.Add(new TXTextControl.TextFormField(1440)); } catch (TXTextControl.LicenseLevelException exception) { MessageBox.Show(this, exception.Message, "Not available", MessageBoxButtons.OK, MessageBoxIcon.Information); } } ``` ### Handle Errors of Background Work An exception thrown inside `Task.Run` doesn't reach the user directly. It is stored in the task and thrown again where the task is awaited, on the UI thread, where a `try` block around the `await` catches it. The handler needs `using System.Threading.Tasks;` at the top of *Form1.cs*: ```csharp private async void convertButton_Click(object sender, EventArgs e) { try { await Task.Run(() => { using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) { if (!tx.Create()) { throw new InvalidOperationException("TX Text Control could not be initialized."); } tx.Load("contract.docx", TXTextControl.StreamType.WordprocessingML); tx.Save("contract.pdf", TXTextControl.StreamType.AdobePDF); } }); MessageBox.Show(this, "contract.pdf created."); } catch (TXTextControl.FilterException exception) { MessageBox.Show(this, $"{exception.Reason}: {exception.Message}", "Conversion failed"); } } ``` The `using` block disposes the `ServerTextControl` also when an exception leaves it. [Using ServerTextControl in Desktop Applications](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/servertextcontrol/llms-full.txt) describes background work. When a merge is canceled from a `DataRowMerged` handler, catch the `MergeCanceledException` in the same way around the merge; [Merge Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/events/llms-full.txt) shows the event. ### Catch Exceptions Nobody Handled An exception that no `catch` block handles ends the application. To log such exceptions and show a message instead, handle the [Application.ThreadException](https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.application.threadexception) event of Windows Forms in *Program.cs* before the form is shown. Use it as a last resort, and catch exceptions where you call TX Text Control whenever your code can react to them. ### Next Steps - [Troubleshooting](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/llms-full.txt): error messages and their fixes. - [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/llms-full.txt): every `FilterException` reason. - [Loading Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/loading/llms-full.txt): load settings for protected and special documents. - [Handling Untrusted Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/security/untrusted-documents/llms-full.txt): documents from unknown sources. --- ## Nearby - **Previous:** [Using ServerTextControl in Desktop Applications](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/servertextcontrol/llms-full.txt) - **Next:** [Conditional Instructions](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/conditional-instructions/llms-full.txt)