[Docs D-27] Troubleshooting — PDF embedding issues (embedXML: true)

[nielsdrost7]

Wiki section: Troubleshooting
Tier: 4 — Troubleshooting
Publish when: InvoicePlane v1.8.0 is released

---

Which formats use PDF embedding

Only Factur-X and ZUGFeRD configs have embedXML: true. All other formats produce standalone XML files.

Config family	embedXML	Embedded filename
Facturxv10*.php	true	factur-x.xml
Zugferdv23*.php	true	zugferd-invoice.xml
Zugferdv10.php	true	zugferd-invoice.xml
All UBL CIUS variants	false	N/A
KSeF, FatturaPA, Facturae	false	N/A

---

The PDF/A-3 requirement

Factur-X and ZUGFeRD require the PDF to be PDF/A-3 (ISO 19005-3). A regular PDF/A-1 or plain PDF will fail if a validator checks the container format.

Verify your InvoicePlane PDF library produces PDF/A-3 output. If not, the XML attachment will still be present and readable, but the combined file may fail strict validator checks.

---

Checking whether the XML is embedded

Method 1 — file manager

Open the PDF in a reader that shows attachments (e.g. Adobe Acrobat, Evince). Look for the "Attachments" panel. The file factur-x.xml or zugferd-invoice.xml should appear.

Method 2 — command line

# Using pdfdetach (poppler-utils)
pdfdetach -list invoice.pdf

# Extract all attachments
pdfdetach -saveall invoice.pdf

Method 3 — unzip

PDF files are ZIP archives at a low level:

unzip -l invoice.pdf

The embedded XML will appear as an entry inside the archive.

---

Common problems

XML not embedded at all

Symptom: No attachment visible in PDF reader; validator reports "no XML attachment found"

Causes:

• embedXML is set to false in the config (check the config file)
• The PDF library does not support PDF/A-3 embedding
• An exception was thrown during XML generation but silently swallowed

Fix: Check the InvoicePlane error log. Verify the PDF library version supports embedding.

Wrong filename in the embedded attachment

Symptom: Validator reports "attachment must be named factur-x.xml" (or zugferd-invoice.xml)

Cause: XMLname in the config is set to the wrong value

Fix:

// Factur-X
'XMLname' => 'factur-x.xml',

// ZUGFeRD
'XMLname' => 'zugferd-invoice.xml',

XML validates alone but PDF/A-3 fails

Symptom: XML extracted from PDF passes validation; combined PDF fails PDF/A-3 conformance check

Cause: PDF library does not set the correct PDF/A-3 conformance metadata

Fix: Upgrade the PDF library, or accept standalone XML export for now using embedXML: false with the same generator while investigating.

---

Migrated from InvoicePlane/InvoicePlane-e-invoices#51.