Images from docx-templates not rendering in editor — only last image shown in all slots

[elizabeth18-nh]

What happened?

When loading a DOCX file generated by docx-templates (v4.15.0) that contains multiple inline images, SuperDoc renders only the last image in every image slot. All other image slots show the same last image repeated. The DOCX opens correctly in Microsoft Word, Google Docs, and LibreOffice — the issue is specific to the SuperDoc editor.

Steps to reproduce

Generate a DOCX using docx-templates with multiple images inserted via an image loop (e.g. 3 property photos)
Load the resulting DOCX into SuperDoc via docxUrl
Observe all image slots render the same last image

SuperDoc version

1.16.0

Additional context

Expected behavior

Each image slot should display its own distinct image, matching the output in Word/Google Docs/LibreOffice.

Actual behavior

Only the last image renders — it appears in every slot.

Root cause identified

After inspecting the raw DOCX XML we found two issues introduced by the docx npm package (used internally by docx-templates):

Duplicate pic:cNvPr id="0" on all images — every inserted image has id="0" on the pic:cNvPr element. Per the OOXML spec (§20.2.2.3) this ID must be unique within the document. ProseMirror likely uses this ID as a node key and deduplicates — rendering only the last image for all slots.

<pic:cNvPr id="0" name="image1.jpg"/>
<pic:cNvPr id="0" name="image2.jpg"/>
<pic:cNvPr id="0" name="image3.jpg"/>
Non-standard relationship IDs — docx-templates generates relationship IDs in img{hash} format instead of the standard rId{n} convention:

Environment

Version

@harbour-enterprises/superdoc 1.16.0
docx-templates 4.15.0
Browser Chrome 122
Node.js 20.x

Possible fix

SuperDoc could defensively reassign unique IDs to any pic:cNvPr elements that share id="0" during DOCX load, similar to how Word handles this gracefully. Alternatively, documenting that SuperDoc requires standard rId{n} relationship IDs would help integrators know to pre-process their DOCX files.

Additional context

Confirmed images ARE present in the DOCX zip (correct EMU dimensions found in XML)
Images are NOT inside a table — they are in standalone <w:p> paragraphs
The bug is not related to file size — tested with files ranging from 1MB to 12MB with identical results
Downloads (PDF, Word) correctly show all distinct images — the issue is editor rendering only

[linear]

IT-632

[caio-pizzol]

Hey @elizabeth18-nh! Thanks for the detailed investigation - both the issue report and the investigation post were really helpful in understanding the problem.

We've been digging into this and traced through our entire image loading pipeline. We're pretty confident the duplicate pic:cNvPr id="0" values aren't the direct cause - those IDs aren't used as lookup keys in our import.

Do you mind sharing the DOCX file that's causing this? We're also going to try to replicate it by creating one through docx-templates, but having the exact file would be really helpful to confirm the root cause.

[elizabeth18-nh]

Thanks for looking into it! Totally understand — happy to help replicate it.

Since the file has client data I can't share it directly, but I can share the raw XML snippets that don't contain any sensitive content. Here are the key parts from the broken file:

word/_rels/document.xml.rels — non-standard relationship IDs:

word/document.xml — all three images share id="0":

<pic:cNvPr id="0" name="image1.jpg"/>
<pic:cNvPr id="0" name="image2.jpg"/>
<pic:cNvPr id="0" name="image3.jpg"/>
I'll also put together a minimal repro using docx-templates directly with dummy images and share that separately — that should be cleaner for your team to test with. Will post it here once ready.

In the meantime, curious if pic:cNvPr id isn't used as a lookup key in your import, what is used to uniquely identify drawing nodes internally? That might help narrow down where the deduplication is happening.

[caio-pizzol]

Thanks for looking into it! Totally understand — happy to help replicate it.

Since the file has client data I can't share it directly, but I can share the raw XML snippets that don't contain any sensitive content. Here are the key parts from the broken file:

word/_rels/document.xml.rels — non-standard relationship IDs:

word/document.xml — all three images share id="0":

<pic:cNvPr id="0" name="image1.jpg"/> <pic:cNvPr id="0" name="image2.jpg"/> <pic:cNvPr id="0" name="image3.jpg"/> I'll also put together a minimal repro using docx-templates directly with dummy images and share that separately — that should be cleaner for your team to test with. Will post it here once ready.

In the meantime, curious if pic:cNvPr id isn't used as a lookup key in your import, what is used to uniquely identify drawing nodes internally? That might help narrow down where the deduplication is happening.

Providing context to help replicable issues is always helpful! So thank you!

To answer your question: we don't use pic:cNvPr id as a lookup key internally - the piece that actually connects each image to its file is the r:embed attribute on <a:blip>. We built a repro with the same pattern you described (duplicate id="0", non-standard relationship IDs) and images loaded correctly, so the missing piece for us is the actual <a:blip r:embed="..."/> values from each <w:drawing> block - could you share those?

That'll tell us whether each image is pointing to a different relationship or if they're all referencing the same one.

[elizabeth18-nh]

We ran the debug and got the actual <a:blip r:embed> values from our DOCX:

r:embed="img2073076884" → media/image4.png
r:embed="img2073076885" → media/image5.png
r:embed="img2073076886" → media/image6.png
Each r:embed value is unique and points to a different media file, so the DOCX structure looks correct at the relationship level.

The relationship IDs use a non-standard img{hash} format (generated by docx-templates) instead of the usual rId{n} format. We suspect SuperDoc's _rels resolver may only handle IDs starting with rId, causing all 3 images to fail resolution, resulting in only the last image rendering in all 3 slots.

Could you confirm whether SuperDoc's relationship parser is format-sensitive on the ID prefix? We're working around it on our side by normalizing the IDs before upload, but would appreciate knowing if this is a known limitation.