# Mail Merge > Fix mail merge problems in TX Text Control .NET for Windows Forms: empty or vanishing fields, blocks that don't repeat, empty lines, formats and exceptions. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Troubleshooting > Mail Merge - **2163 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/mail-merge/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/mail-merge/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/mail-merge/llms-full.txt --- A mail merge with [MailMerge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/llms-full.txt) rarely fails with an error. More often, it succeeds and the result isn't what you expected: a field is empty or gone, a block isn't repeated, or a date has the wrong format. The problems below start from what you see in the merged document. [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/llms-full.txt) shows a working merge to compare with. ### A Merge Field Disappears or Stays Empty A merge field of the template isn't in the merged document, or it is there without a value. `MailMerge` fills a field from the column or property whose name matches the name of the field, at the level of the data the field is in; fields of child data use dot notation, such as `address.street`. When no column matches, the field gets no value, and because [RemoveEmptyFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/removeemptyfields-property/llms-full.txt) is `true` by default, it is removed. With business objects, the property names are the field names, and the first object of a collection defines the structure: objects of other types leave some fields empty. 1. Set `RemoveEmptyFields` to `false`, so that fields without data stay in the document and you can see which ones they are. 2. Handle [FieldMerged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/fieldmerged-event/llms-full.txt) and mark every field whose [Merged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge-fieldmergedeventargs/merged-property/llms-full.txt) is `false`, as [Show a Text for Fields Without Data](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/fields/#show-a-text-for-fields-without-data) shows. 3. Correct the field name in the template or the column name in the data. The blog article [MailMerge: Field Mapping and Handling of Unmerged Fields](https://www.textcontrol.com/blog/2022/05/04/mailmerge-field-mapping-and-handling-of-unmerged-fields/) describes the mapping in detail. ### Empty Lines Remain Where Fields Had No Data An address or a list has blank lines where fields without data were. Removing an empty field doesn't remove the line it was on. 1. Keep `RemoveEmptyFields` at `true`. 2. Set [RemoveEmptyLines](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/removeemptylines-property/llms-full.txt) to `true`, which removes lines that are empty after the merge. Its default is `false`. 3. For images without data, set [RemoveEmptyImages](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/removeemptyimages-property/llms-full.txt) to `true`. ### A Merge Block Isn't Repeated or Disappears A section of the template that should repeat for each record appears once, with empty fields, or it is missing from the result. A merge block is a subtext part whose name starts with the prefix that [MergeBlockNamePrefix](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergeblocknameprefix-property/llms-full.txt) returns, `txmb_`. The rest of the name must match the name of the table, or of the collection property of a business object, that holds the records. A block without data is removed, because [RemoveEmptyBlocks](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/removeemptyblocks-property/llms-full.txt) is `true` by default. In a template from Microsoft Word, blocks are bookmarks, which are loaded as subtext parts only on request. 1. Check that the block name starts with `txmb_` and that the rest matches the name in the data, for example `txmb_Items` for a property `Items`. 2. If the block disappears, check that the data contains records for it, or set `RemoveEmptyBlocks` to `false` to see the empty block. 3. When you load a Word template into the editor, set [LoadSettings.LoadSubTextParts](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/loadsettings/loadsubtextparts-property/llms-full.txt) to `true`, as [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/#word-fields-are-missing-after-loading) describes. [Add Repeating Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/blocks/llms-full.txt) shows a working block. The blog article [MailMerge: Removing Empty Blocks](https://www.textcontrol.com/blog/2016/02/15/mailmerge-removing-empty-blocks/) explains the removal. ### Numbers or Dates Are Parsed or Formatted Wrongly A date or a number in the merged document is wrong, or it has the format of another country. Values in the data are parsed with [DataSourceCulture](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/datasourceculture-property/llms-full.txt) and formatted with [MergeCulture](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergeculture-property/llms-full.txt). Both default to the culture of the current thread, which differs between machines, as [Parse Numbers and Dates With the Right Culture](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/data-sources/json-xml/#parse-numbers-and-dates-with-the-right-culture) explains. 1. Set `DataSourceCulture` to the culture your data is written in. 2. Set `MergeCulture` to the culture the document should show. 3. Merge again. ### MergeJsonData Throws a ParserException [MergeJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergejsondata-method/llms-full.txt) throws an exception derived from [ParserException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-json/parserexception/llms-full.txt). The JSON string isn't valid, or it doesn't have the shape `MergeJsonData` expects: a single object or an array of objects with the same structure. The derived class tells you what is wrong, as the table in [Merge JSON Data](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/data-sources/json-xml/#merge-json-data) lists. 1. Catch `ParserException` around `MergeJsonData` and log the type of the exception. 2. Validate the JSON, and make sure it is one object or an array of objects with the same structure. ### Merge Throws a MergeCanceledException The merge stops with a [MergeCanceledException](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mergecanceledexception/llms-full.txt). Your code canceled the merge: the exception is thrown when a handler of [DataRowMerged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/datarowmerged-event/llms-full.txt) sets [Cancel](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge-datarowmergedeventargs/cancel-property/llms-full.txt) to `true`, for example when a user stops a long merge. 1. Catch `MergeCanceledException` where you call the merge method, and treat it as a canceled merge, not as an error. ### LoadTemplate Returns False [LoadTemplate](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/loadtemplate-method/llms-full.txt) returns `false`, and the merge has no template. The template is invalid or couldn't be loaded. 1. Check the path and the format you pass to `LoadTemplate`. 2. Open the template in the editor to see whether it loads there. [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/llms-full.txt) describes the errors of loading. ### The Merged Document Has the Wrong Page Size or Margins The merged document has the page size and margins of the editor, not those of the template. [UseTemplateFormat](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/usetemplateformat-property/llms-full.txt) is `false` by default. Then `MailMerge` uses the page size and margins of its [TextComponent](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/textcomponent-property/llms-full.txt). 1. Set `UseTemplateFormat` to `true` to keep the page format of the template. ### Merged Content or Images Disappear in an Earlier Service Pack After a merge, table cells lose their content, or merged images in merge blocks are missing, although the data contains values for them. The service packs of version 34.0 fixed several merges that removed content. The Known Issues page of version 34.0 lists, among others, these fixes: | Fixed in | What went wrong in the merge | |---|---| | Service Pack 1 | A memory leak in the `MailMerge` class, and a table header shown above a table cell with a formula | | Service Pack 2 | Merged images in merge blocks were deleted when `RemoveEmptyImages` was `true` | | Service Pack 5 | Merged content was removed when `RemoveEmptyLines` was used inside table cells, a merge removed the complete content of a table cell, and images lost their ID and name | 1. Read the service pack your application runs with from [VersionInfo.ServicePack](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/versioninfo/servicepack-property/llms-full.txt). 2. Install the latest service pack, update `TXTextControl.TextControl.WinForms.SDK` to 34.0.5 and rebuild the application. 3. If the problem remains, check the open issues on the [Known Issues](https://www.textcontrol.com/product/tx-text-control-dotnet-winforms/issue/3400/) page. It lists as open, for example, that [SaveDocumentToMemory](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/savedocumenttomemory-method/llms-full.txt) doesn't work with documents whose merge block bookmarks are in invalid positions. ### The Database Connection Dialog Doesn't Connect to Azure SQL In the **Choose Data Source** dialog box, which the **Select Data Source** button of the **Reporting** tab opens, a connection to an Azure SQL database fails. ![The Reporting tab of TX Text Control Words with the Choose Data Source dialog box listing Microsoft Access, ODBC and SQL Server data sources and a data provider.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/choose-data-source-dialog.7f4159b6.webp) The dialog box is the [DatabaseConnectionDialog](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-windows-forms/databaseconnectiondialog/llms-full.txt), which builds a connection string for the [DataSourceManager](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/llms-full.txt). The Known Issues page of version 34.0 lists as open that it can't connect to Azure SQL databases. 1. Load the data from the Azure SQL database in your own code, for example into a `DataSet`. 2. Merge it with [Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/merge-method/llms-full.txt), as [DataSets and DataTables](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/data-sources/datasets/llms-full.txt) describes. ### Related Pages - [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/llms-full.txt): a first merge, step by step. - [Mail Merge and Reporting](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/llms-full.txt): templates, data sources and merge blocks, explained. - [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/llms-full.txt): templates that don't load as expected. --- ## Nearby - **Previous:** [Document Conversion](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/conversion/llms-full.txt) - **Next:** [Deployment](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/troubleshooting/deployment/llms-full.txt)