python-docx-style-id-mismatch

Installation
SKILL.md

python-docx Style ID Mismatch (OxmlElement)

Problem

When creating Word document paragraphs using python-docx's low-level OxmlElement API, setting w:pStyle with the style's display name (e.g., "Heading 2") causes the paragraph to silently fall back to "Normal" style. No error is raised. The XML requires the style ID (e.g., "Heading2") which differs from the display name.

Context / Trigger Conditions

  • Creating paragraphs via OxmlElement('w:p') instead of doc.add_paragraph()
  • Setting style with pStyle.set(qn('w:val'), 'Heading 2') (WITH space)
  • Paragraphs render as Normal/body text instead of the intended style
  • paragraph.style.name shows "Normal" even though you set a heading style
  • No error or warning is raised -- complete silent failure
  • Affects all styles with spaces in their display names
Related skills
Installs
1
First Seen
Apr 16, 2026