Error Handling

Treat an e-invoice error as a failed document-generation job. Preserve the Magento invoice or credit memo, fix the data or configuration that caused the failure, and then run one controlled retry.

What Block on Error really does

Invoice and credit-memo settings both contain a Block … on E-Invoice Error switch. It can propagate an exception from immediate generation. It is not a transactional guarantee:

the invoice observer runs on sales_order_invoice_save_commit_after, after Magento commits the invoice;
queue and cron failures occur later and cannot block sales-document creation;
configuration errors are stored as error without following the same blocking branch;
unexpected exceptions may propagate regardless of the switch.

Keep this control off during rollout. Build an operations process around status and recovery instead of assuming a failed e-invoice removes the Magento document.

Failure categories

Category	Typical examples	First check
Source data	Missing address, VAT ID, seller contact or buyer reference	Invoice, order and store-view data
Format/configuration	Wrong profile, endpoint scheme, payment code or unsupported activation state	E-Invoice configuration in the document's store view
Validation	Malformed XML or schema mismatch	Exact validation messages and selected version/profile
Hybrid PDF	Magento PDF failure or XML embedding failure	Normal Magento PDF and hybrid output path
Storage	Unwritable/invalid media path or missing file	Storage strategy, path, permissions and free space
Processing	Stopped consumer, cron delay or exhausted retries	Mode, consumer, cron schedule and status age
Delivery	Receiver rejects a locally generated file	Downstream provider or portal response

Notifications

Under Validation & Error Handling, configure:

Enable Error Notifications;
Error Notification Email;
Error Notification Threshold.

The notification service counts failures and sends a message after the configured threshold. Test this in a controlled environment. A notification is an alert, not an automatic correction or delivery retry.

Automatic retries

The shared retry cron runs daily at 04:30. It selects error documents for stores where retries are enabled and respects Max Retry Attempts.

Automatic retry is appropriate for transient file, queue or infrastructure failures. It is not useful for deterministic problems such as a missing VAT ID or an invalid profile. Repeatedly generating unchanged input adds noise without changing the result.

Manual recovery

Open the failed invoice or credit memo.
Record the exact error and numeric entity ID.
Check the store view and selected format/profile.
Fix the underlying source or configuration.
Use Generate E-Invoice once.
Download XML/PDF and validate it.
Deliver through the intended channel and record that downstream result separately.

Use a mass action only after you have proven the correction on one representative document.

Common cases

VAT ID or seller information is missing

Complete the seller fields in the same store view as the sales document. For XRechnung projects, also populate seller contact details. Then regenerate.

XSD validation fails

Confirm the selected format, profile/version and exact schema error. A wrong version cannot be fixed by lowering validation. Correct the document contract or the source fields.

No PDF is available

Only ZUGFeRD and Factur-X are hybrid. For those formats, first prove that Magento's normal invoice or credit-memo PDF renders, then inspect the hybrid builder and stored PDF path.

A PEPPOL receiver rejects the XML

Confirm endpoint schemes, buyer reference, participant registration and provider business rules. The module creates UBL but does not perform access-point transmission or full provider validation.

Factur-X says the format is not configured

Confirm that Enable E-Invoicing is on and Default B2B Format is set to Factur-X in the document's store view. Save the store-view scope and retry. The formatter reads that default-format setting; do not create a hidden enabled-formats setting.

Logs and support data

Review var/log/system.log and var/log/exception.log around the failed entity ID. Share only sanitized excerpts. Include package and Magento compatibility details, store view, format/profile, mode, status and exact error. Do not paste invoice XML containing customer data into public tickets.