[Docs D-26] Troubleshooting — Common validation errors and fixes

[nielsdrost7]

Wiki section: Troubleshooting
Tier: 4 — Troubleshooting
Publish when: InvoicePlane v1.8.0 is released
Related issues: #11 — French PDP rules · #13 — Endpoint fields · #15 — Routing codes

---

EN 16931 / general Peppol rules

Rule	Message	Cause	Fix
BR-50	Payment means must contain IBAN or account	user_iban is empty	Fill IBAN in Settings → User
BR-61	Credit transfer requires financial account	Payment type 30 but no IBAN	Fill IBAN or remove payment type 30
BR-CO-27	BIC must be present if financial institution is present	Bank name set but no BIC	Fill user_bic or remove user_bank
BR-CL-25	Endpoint schemeID not in EAS code list	Invalid client_eas_code or user_eas_code	Check EAS code reference and use a valid code
BR-01	Invoice must have a payment due date	invoice_date_due is null	Set due date on the invoice
BR-04	Invoice must have a seller name	user_company is empty	Fill company name in Settings → User
BR-07	Invoice must have a buyer name	client_company is empty	Fill company name on client record
BR-31	Each line must have a line total	Calculated as 0 due to quantity or price	Check line item data

---

French PDP specific (Factur-X)

Rule	Message	Cause	Fix
BR-FR-01	Invalid GuidelineID	Old extended profile URN still set	Config must use urn:cen.eu:en16931:2017 — see issue #11
BR-FR-02	Invoice ID contains invalid characters	Invoice number has ., #, @, or spaces	Change numbering scheme to use -, _, / only
BR-FR-03	Missing PMT / PMD / AAB notes	French legal payment notes absent	Add PMT, PMD, AAB to invoice terms
BR-FR-04	Seller SIREN missing (BT-30)	user_siren custom field not filled	Fill user_siren in Settings → User → Custom fields

---

German XRechnung

Rule	Message	Cause	Fix
BR-DE-1	BuyerReference (Leitweg-ID) is mandatory	invoice_routing_code_1 is null	Add Leitweg-ID to invoice E-Invoicing section
BR-DE-2	Seller endpoint required	user_tax_code is empty	Fill tax_code in Settings → User
BR-DE-15	Invoice note must not be empty if present	Empty note element	Remove note or fill it

---

Belgian UBL.BE

Rule	Message	Cause	Fix
ubl-BE-01	Two AdditionalDocumentReference required	Config is missing the DocumentReference option	Use the standard Ublciusv131be.php config which includes this
ubl-BE-02	DocumentType must be CommercialInvoice or CreditNote	Generator not setting document type	Verify invoice_sign field is set on the invoice
ubl-BE-15	TaxCategory/Name missing or invalid	VAT rate not in TaxName mapping	Use only 21, 12, 6, or 0% on Belgian invoices
ubl-BE-10	TaxSubtotal/TaxCategory/Name not in BTCC list	Same as above	Same fix

---

Dutch NLCIUS / SI-UBL

Rule	Message	Cause	Fix
BR-NL-1	Seller legal entity identifier required (KvK or OIN)	user_tax_code empty	Fill KvK number in Settings → User
BR-NL-5	AllowanceChargeReasonCode present	Config does not have NoReasonCode: true	Ensure Nlciusciiv10.php or Ublsi20nl.php is used unmodified
SI-specific	PaymentMeansCode name attribute present	Config does not have NoPaymentMeansName: true	Ensure Ublsi20nl.php is used unmodified

---

Polish KSeF

Rule	Message	Cause	Fix
FA-3 schema error	Invalid VAT rate	Rate not 23, 8, or 5%	Only use supported Polish VAT rates
FA-3 schema error	Missing PLN exchange rate	Foreign currency invoice but no exchange rate	Fill pln_exchange_rate custom field
FA-3 schema error	Corrective invoice not supported	You are generating a credit note	KSeF generator does not support corrective invoices yet

---

General debugging tips

1. Extract the XML first — for embedded formats, extract the XML from the PDF before validating (see Validation guide)
2. Validate against the right profile — make sure the validator is set to the same profile as your GuidelineSpecifiedDocumentContextParameterID
3. Check empty fields — most validation failures trace to a missing or empty InvoicePlane field; use the Data mapping reference to find which field feeds which element
4. Test with a simple invoice — one line item, no global discount, standard VAT rate; add complexity only after the base case passes

---

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