1. IronWord
  2. Troubleshooting
  3. Header Disappears After SaveAs in IronWord

Header Disappears After SaveAs in IronWord

Curtis Chau
Curtis Chau
Updated:

Please noteThis behavior has only been reported in one environment and is not corroborated by IronWord's changelog — other IronWord guides use SaveAs() as their standard save call with no reported header loss. Treat this as a possible environment-specific quirk rather than a confirmed product defect, and verify against your own environment before applying the workaround below.

In some environments, populating a DOCX template with IronWord and writing the result with SaveAs() has been observed to drop the template's header from the generated file, even though the placeholders merge correctly.

Header (e.g. "City Attorney Cover Sheet") is visible in the original DOCX
but missing in the generated file after calling SaveAs().

Word template with unreplaced placeholders and no header

In the environment where this was observed, the header was preserved when writing the document with Save() rather than SaveAs(). This has not been corroborated across other environments or in IronWord's changelog — other IronWord guides use SaveAs() as their standard save call without a header-loss issue, so treat this as environment-specific rather than a confirmed product defect.

Solution

1. Load the Template

Open the source DOCX with WordDocument.

using IronWord;
using System.Collections.Generic;

var templatePath = @"C:\Templates\CityAttorneyCoverSheetTemplate.docx";
var outputPath   = @"C:\Output\merged.docx";

var doc = new WordDocument(templatePath);
using IronWord;
using System.Collections.Generic;

var templatePath = @"C:\Templates\CityAttorneyCoverSheetTemplate.docx";
var outputPath   = @"C:\Output\merged.docx";

var doc = new WordDocument(templatePath);
Imports IronWord
Imports System.Collections.Generic

Dim templatePath As String = "C:\Templates\CityAttorneyCoverSheetTemplate.docx"
Dim outputPath As String = "C:\Output\merged.docx"

Dim doc As New WordDocument(templatePath)
$vbLabelText   $csharpLabel

2. Replace the Placeholders

Merge your values through doc.Texts, a straightforward find/replace approach; for placeholder-heavy templates using MERGEFIELD syntax, IronWord's dedicated WordDocument.MailMerge API is also available.

var replacements = new Dictionary<string, string>
{
    ["{CaseNumber}"] = "2026-CR-12345",
    ["{DefendantName}"] = "John Doe",
    ["{DefendantAge}"] = "34",
    ["{DefendantAttorney}"] = "Jane Smith",
};

foreach (var kv in replacements)
{
    doc.Texts.ForEach(t => t.Replace(kv.Key, kv.Value));
}
var replacements = new Dictionary<string, string>
{
    ["{CaseNumber}"] = "2026-CR-12345",
    ["{DefendantName}"] = "John Doe",
    ["{DefendantAge}"] = "34",
    ["{DefendantAttorney}"] = "Jane Smith",
};

foreach (var kv in replacements)
{
    doc.Texts.ForEach(t => t.Replace(kv.Key, kv.Value));
}
Imports System.Collections.Generic

Dim replacements As New Dictionary(Of String, String) From {
    {"{CaseNumber}", "2026-CR-12345"},
    {"{DefendantName}", "John Doe"},
    {"{DefendantAge}", "34"},
    {"{DefendantAttorney}", "Jane Smith"}
}

For Each kv In replacements
    doc.Texts.ForEach(Sub(t) t.Replace(kv.Key, kv.Value))
Next
$vbLabelText   $csharpLabel

Iterating each entry over doc.Texts swaps every placeholder token for its merge value across the document body.

3. Save With Save(), Not SaveAs()

In the environment where this issue was observed, writing the output with doc.Save(outputPath) kept the header intact, while doc.SaveAs(outputPath) dropped it. Treat this as a workaround to try, not a confirmed universal behavior difference between the two methods.

doc.Save(outputPath);
doc.Save(outputPath);
doc.Save(outputPath)
$vbLabelText   $csharpLabel

Merged Word document with header preserved and placeholders filled

Notes

  • If your workflow requires SaveAs(): verify on the latest IronWord version whether the header survives in your environment.
  • If the issue reappears: pin to a previously working version as a short-term mitigation while the behavior is investigated.

Please notePlaceholders are still found and replaced during traversal even when the header is lost, so a successful merge alone is not confirmation the header was kept. Open the output and check.

Curtis Chau
Curtis Chau
  Chat with engineering team now
Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Read More
Ready to Get Started?
Nuget Downloads 49,216 | Version: 2026.7 just released
Still Scrolling Icon

Still Scrolling?

Want proof fast? PM > Install-Package IronWord
run a sample watch your data become a Word doc.