Why generated PPTX files trigger the repair dialog

PowerPoint's repair dialog is triggered by OOXML violations that standard validators do not catch. The 7 most common causes in programmatically generated files are: incorrect XML element ordering, missing required attributes, duplicate relationship IDs, malformed chart XML from combo chart workarounds, unescaped special characters in hyperlinks, corrupted embedded images, and AI code assistants producing approximate OOXML.

Why do OOXML validators miss repair-triggering errors?

The first thing every developer does after seeing the repair dialog is run their PPTX through an OOXML validator. And every time, the validator reports zero errors.

According to a May 2023 thread on Microsoft Q&A, a developer found that both the OOXML validator VS Code extension and the Open XML SDK 2.5 Productivity Tool reported no errors on a file that consistently triggered the repair dialog. The root cause turned out to be a missing typeface attribute on an <a:ea> element — an attribute that the published XSD schema marks as optional but PowerPoint treats as mandatory.

This is the fundamental problem: PowerPoint enforces stricter rules than the published OOXML specification. Microsoft's implementation validates against internal rules that are not fully documented in the ISO 29500 standard or the published XSD schemas. According to another Microsoft Q&A report from 2025, a developer compared repaired and original files using the Open XML Productivity Tool, found no visible differences, and spent weeks without resolution — ultimately requiring Microsoft's internal Open Specifications team to investigate.

This is why programmatic PPTX generation is harder than it appears. Libraries like PaperJSX, PptxGenJS, and python-pptx exist specifically to abstract away these undocumented rules. When repair dialogs appear in generated files, it means the library missed one.

Can XML element ordering trigger repair?

What happens: PowerPoint requires child elements within certain parent nodes to appear in a specific order. The XSD schema allows flexibility, but PowerPoint does not.

Evidence: According to Open XML SDK issue #1226, an upgrade from SDK version 2.7.2 to versions 2.11–2.18 changed the order of AlternateContent and p:sldLayoutIdLst elements within slide masters. The reordering caused PowerPoint to prompt for repair on every generated file. Manually restoring the original element order fixed the issue.

Where it bites: This affects any library or SDK that generates slide masters, slide layouts, or theme XML. The issue is invisible to validators because the XSD schema uses <xs:all> or <xs:sequence> groupings that technically allow either order.

Fix: If you are generating raw OOXML, compare your element order against a file created by PowerPoint itself. Unzip a known-good .pptx (rename to .zip), examine the relevant XML files, and match the element sequence exactly. If you are using a library, update to the latest version — this class of bug is typically fixed in patch releases.

2. Missing required attributes

What happens: PowerPoint requires certain attributes on font, color, and shape elements that the XSD schema marks as optional. Their absence triggers repair.

Evidence: The Microsoft Q&A case cited above traced a repair dialog to a missing typeface attribute on <a:ea> (East Asian font) elements inside theme1.xml. After repair, PowerPoint silently applied default fonts and changed colors — meaning the "repaired" file looked different from the intended output.

Where it bites: Theme XML, font definitions, and text run properties. According to Anthropic's OOXML reference, common required-but-undocumented attributes include dirty="0" on <a:rPr> and <a:endParaRPr> elements, and xml:space='preserve' on <a:t> elements containing leading or trailing whitespace.

Fix: Add dirty="0" to all text run properties. Ensure every <a:ea> and <a:cs> element has a typeface attribute. Use xml:space="preserve" on text elements. When in doubt, compare against PowerPoint's own output — create the equivalent slide manually, save, unzip, and inspect the XML.

How do duplicate relationship IDs corrupt a file?

What happens: PPTX files use relationship IDs (rId1, rId2, etc.) to link slides, images, charts, and hyperlinks. Duplicate IDs within a single .rels file cause PowerPoint to discard one of the referenced objects.

Evidence: According to the PptxGenJS v4.0.1 release notes, hyperlinks in auto-paged tables caused repair dialogs because the pagination logic duplicated relationship IDs across the original and overflow slides (issue #1392). Earlier versions also had duplicate IDs when hyperlinks coexisted with other objects on the same slide (fixed in issue #477).

Where it bites: Table auto-paging, slides with multiple hyperlinks, slides that combine images and charts, and any operation that copies elements between slides.

Fix: Ensure every relationship ID is unique within its .rels file. Use a monotonically incrementing counter per-slide, not a global counter. If you are using PptxGenJS, update to v4.0.1 or later. If generating raw OOXML, audit the _rels/ directories inside the unzipped PPTX for duplicate Id attributes.

# unzip and inspect a PPTX file's relationship IDs
unzip -o report.pptx -d report_extracted
grep -r 'Id="rId' report_extracted/ppt/slides/_rels/ \
  | awk -F'"' '{print $2}' \
  | sort \
  | uniq -d

If that command produces any output, you have duplicate relationship IDs.

4. Combo chart XML splicing

What happens: Libraries that do not natively support combo charts force developers to splice XML from two separate chart objects. This almost always produces invalid OOXML.

Evidence: According to python-pptx issue #338, opened in November 2017, the standard workaround for creating a combo chart (bar + line) involves generating two separate charts, extracting the <c:lineChart> element from one, and inserting it into the other's <c:plotArea>. The original reporter noted that "when I open test.pptx, it shows it needed repairing." Subsequent commenters confirmed the same result.

The workaround fails because the spliced chart element references data from its original embedded Excel workbook, which does not exist in the destination chart's chartN.xml data source. PowerPoint detects the orphaned data reference and triggers repair.

Where it bites: Any python-pptx user who needs a bar-and-line overlay on the same chart. The python-pptx documentation explicitly states it "doesn't yet support creating multi-plot charts," and this limitation remains unresolved after 8 years.

Fix: There is no reliable fix within python-pptx. Two alternatives support combo charts natively:

• PptxGenJS — supports combo charts as a first-class feature. Pass multiple series with different type properties to addChart(). (See the PptxGenJS gotchas for other repair-triggering pitfalls.)
• PaperJSX — supports combo charts in the Pro tier via the JSON schema. Set chartType: "combo" and define per-series types in the data object. The python-pptx vs PptxGenJS vs PaperJSX comparison covers the tradeoffs in full.

What about unescaped special characters?

What happens: Ampersands (&), angle brackets (< >), and certain Unicode characters in text content or hyperlink URLs produce malformed XML.

Evidence: According to PptxGenJS's changelog, issue #562 documented hyperlinks containing & characters creating malformed slides. Issue #633 documented non-integer margin values producing invalid XML because XML does not accept floating-point precision mismatches in certain attributes. Both were fixed by adding proper escaping and rounding.

Where it bites: User-supplied text, URLs from databases, data labels pulled from APIs — any content that is not sanitized before being inserted into the OOXML XML tree.

Fix: Escape all text content before XML insertion. At minimum: & → &, < → <, > → >, " → ". For URLs in hyperlinks, percent-encode the query string. Libraries like PaperJSX and current versions of PptxGenJS handle this automatically.

6. Corrupted embedded images

What happens: An image file embedded in the PPTX's ppt/media/ directory is truncated, in an unsupported format, or has mismatched content type headers.

Evidence: According to a developer report on CopyProgramming, a PPTX generated from a template consistently triggered the repair dialog despite passing validation. After a week of debugging, the root cause was identified: a logo image in the template file was corrupted. The corruption was invisible in recent PowerPoint versions but caused errors in Office 2007 and 2010.

PptxGenJS has also documented image-related repair issues: uppercase file extensions in image paths caused repair dialogs (issue #860, fixed in v3.12), and SVG images in slide masters triggered repair in some PowerPoint versions (issue #1150).

Fix: Validate image files before embedding. Check that file headers match the declared content type. Use lowercase file extensions. For SVGs, test in PowerPoint 2019+ (older versions do not support SVG). If using template files, verify every embedded image individually.

Why does AI-generated OOXML fail?

What happens: AI code assistants (GitHub Copilot, OpenAI Codex, Claude) generating raw OOXML produce XML that approximates the correct structure but violates the undocumented rules PowerPoint enforces.

Evidence: According to OpenAI Codex issue #16315, filed in March 2026, AI-generated PPTX files consistently trigger the repair dialog. PowerPoint removes "unreadable content" during repair, stripping out elements the AI produced incorrectly. The issue is filed under the "agent" and "bug" labels and remains open.

This is not a solvable problem through prompt engineering. OOXML is a complex specification — ISO 29500 runs to 7,000+ pages

— and PowerPoint's internal validation rules are not fully captured in public documentation. An LLM generating raw XML will inevitably produce structures that violate these undocumented constraints.

Fix: Never have an AI generate raw OOXML. Instead, use a validated library as an intermediary. With PaperJSX, the AI generates JSON (a format LLMs handle well), and the library converts it to valid OOXML. PaperJSX's MCP server is designed for exactly this workflow — the AI agent produces structured JSON, never touches XML.

Summary: cause → fix table