Header Disappears After SaveAs in IronWord

Updated: August 2, 2026

Please note: This 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().

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

Text

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);

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));
}

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);

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 note: Placeholders 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

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.

...