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
errorwithout 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 var/ path or missing file |
Storage strategy, path, permissions and free space |
| Processing | Stopped consumer, cron delay or stuck claim | 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 recovery — and what is not retried
The hourly einvoice_process_scheduled worker reclaims queued and processing rows whose claim is older than the flow's Recovery Timeout (Minutes) (default 30). That covers transient interruptions such as a crashed consumer or a killed worker.
Documents already marked error are not retried automatically. Recovery is deliberate: fix the cause, then regenerate through the detail-page Generate E-Invoice action (it applies force for error rows) or the REST endpoint with force: true. Grid mass actions and einvoice:generate run without force, so they skip generated documents and cannot retry an error document.
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 on the detail page once — for an
errorrow it appliesforceautomatically. - Download XML/PDF and validate it.
- Deliver through the intended channel and record that downstream result separately.
Grid mass actions do not apply force; use them for first-time generation of unprocessed rows, not for retrying error documents.
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.