ZUG-FILENAME-001:ZUGFeRD/Factur-X Wrong Embedded XML Filename
Fix: Rename the embedded XML to factur-x.xml and update fx:DocumentFileName XMP property.
The embedded XML in your ZUGFeRD/Factur-X PDF has the wrong filename. It must be exactly factur-x.xml since ZUGFeRD 2.1.
Engine Classification
Financial or legal field · Modification blocked by policy
What is ZUG-FILENAME-001?
ZUG-FILENAME-001 is a fatal validation rule defined in the zugferd specification. It validates the UF in the filespec dictionary must match. element under A-3 allows any attachment name, but ZUGFeRD 2.1+ mandates factur-x.xml (case-sensitive). Both > F and in the UBL invoice XML.
When this rule fires, the invoice is rejected by Peppol access points and never reaches the buyer.
Target path: PDF/A-3 allows any attachment name, but ZUGFeRD 2.1+ mandates factur-x.xml (case-sensitive). Both /F and /UF in the filespec dictionary must match.
Why This Error Matters
Wrong filename makes structured data invisible to automated processing systems.
ZUG-FILENAME-001 is a hard failure — the invoice must be corrected and re-sent before it can reach the recipient.
Structured data invisible. Does not meet German e-invoicing requirements.
Validator Behavior
- ·Causes invoice rejection
- ·Error returned: ZUG-FILENAME-001
- ·Specification: zugferd
How to Fix It
Before / After
/F (ZUGFeRD-invoice.xml)
/F (factur-x.xml)
Technical Reference
PDF/A-3 allows any attachment name, but ZUGFeRD 2.1+ mandates factur-x.xml (case-sensitive). Both /F and /UF in the filespec dictionary must match.Common Causes
- ·Using ZUGFeRD 1.0 legacy filename ZUGFeRD-invoice.xml.
- ·PDF library auto-naming.
- ·Case sensitivity issue.
- ·Multiple XML attachments.
Seeing this in production? The API handles ZUG-FILENAME-001 automatically. See the fix response →
Commonly Seen In
Frequently Asked Questions
Exactly factur-x.xml (lowercase).
Yes. Must be lowercase.
Related Errors
Related Content
Last updated: 25 March 2026
Validate your invoice
Drop your XML here to check for ZUG-FILENAME-001
Detect ZUG-FILENAME-001 before submission
This error involves a financial field that can't be auto-modified. We'll flag it with a clear diagnosis so you can fix it at the source.