Understanding invoice statuses and fixing problems

Understanding invoice statuses

Invoices (both outgoing and incoming invoices) pass through various status values during their lifecycle. Understanding these status values helps you identify and fix problems faster.

Main invoice statuses

Asynchronous processing

An important point is that PDF generation and other invoice processing steps run asynchronously. This means:

• When you create an invoice, it is saved in the database immediately.
• The PDF file is not generated immediately but processed in the background.
• During this processing, the invoice may not be available for download.
• This intermediate state is normal and not an error.

Common problems and solutions

The invoice is not available as a PDF

Symptom: The invoice has been created, but the PDF file cannot be downloaded.

Cause: The PDF is generated asynchronously in the background. Depending on system load, this can take a few seconds to minutes.

Solution:

1. Wait a few seconds and reload the page.
2. Try downloading the PDF again.
3. If the problem persists after several minutes, check whether errors occurred when the invoice was created (see the section "PDF generation errors").

PDF generation errors

Symptom: The PDF still cannot be downloaded after a longer time.

Common causes:

• Invalid or incomplete invoice data
• Problems with custom signatures or images
• File format incompatibility

Steps to fix it:

1. Check all required fields in the invoice (recipient, amount, tax rates).
2. Check whether all inserted files or images are in the correct format.
3. Try editing the invoice and saving it again.
4. Temporarily remove all attachments and try generating the PDF again.

Message "File could not be loaded" in the PDF preview

This message appears in the preview if there is no file to display yet or loading has failed. It concerns the same preview component that faktoora uses for invoices as well as for other documents (e.g. cover letters):

Steps to fix it:

1. Wait a moment if the document has only just been created; the PDF is generated asynchronously (see above).
2. Reload the page and open the preview again.
3. If the message persists, check whether the document has been filled in completely (missing required information can prevent generation).

Incoming invoices do not appear in the system

Symptom: An invoice that has been received (by email or upload) is not shown in the system.

Common causes:

• The import process is still running (asynchronously)
• Validation errors in XRechnung/ZUGFeRD files
• Missing permissions for the upload
• The email address is not configured correctly

Steps to fix it:

1. For uploads: wait until the import is complete. The status is shown on the import page.
2. By email: check whether the incoming email address is set up correctly (see "Receiving invoices via your own mail server").
3. Validation errors: if you upload an XRechnung and a validation error occurs, check the XML file for conformance with the XRechnung standard.
4. Permissions: make sure you have permission to create incoming invoices.

XRechnung import errors

Symptom: "Validation error" when importing an XRechnung or ZUGFeRD file.

Causes:

• The XML file does not comply with the XRechnung specification
• Required fields are missing or invalid
• The file is damaged or is not uploaded completely

Steps to fix it:

1. Check whether the file really is a valid XRechnung or ZUGFeRD file.
2. Upload the file again (drag and drop can fail if the connection is interrupted).
3. If the error persists, contact the invoice issuer and ask for a file that complies with the standard.
4. As a workaround, you can record the invoice manually (see "Create/record incoming invoices").

Attachments cannot be downloaded

Symptom: The paper clip icon is shown, but the download fails or the file is not available.

Causes:

• The attachment is still being processed
• The attachment was too large to upload (max. 75 MB per file)
• A storage problem during upload

Steps to fix it:

1. Wait a few seconds and try again.
2. Check the file size (max. 75 MB).
3. Upload the file again if the first upload may have failed.

Search does not find incoming invoices

Symptom: When searching for incoming invoices (e.g. by sender or invoice number), no hits are shown even though the invoices exist.

Causes:

• The invoice has just been imported and the search index has not been updated yet.
• A typo in the search text
• The sender was not recorded correctly

Steps to fix it:

1. Wait a few seconds and try the search again.
2. Reload the page to update the search index.
3. Try searching with different search terms (e.g. only the company name instead of the full address).
4. Check the spelling of the search terms.

An invoice with several attachments is not processed

Symptom: An incoming email with several attachments is not processed correctly, or it is unclear which attachment is the invoice.

Causes:

• The system cannot automatically detect which attachment is the actual invoice
• Several invoices in one email are processed individually

Steps to fix it:

1. Upload invoices individually if possible.
2. Send invoices individually by email instead of several invoices in one email.
3. Name attachments clearly (e.g. "Invoice_2024_001.pdf") so that they are easier to identify.

Checking the invoice status

You can check the current processing status of an invoice:

1. In the dashboard: open the invoice details and check the status shown.
2. By reloading: reload the page to see the latest status.
3. Via the API: if you use the API, you can query the invoice status via the corresponding endpoint.

When is professional support needed?

Contact support if:

• An invoice has not been available as a PDF for hours
• Incoming invoices regularly fail to arrive
• XRechnung imports fail consistently
• Attachments are systematically lost
• Permission errors occur during upload

In these cases, have the following ready:

• The invoice ID or faktoora ID
• Timestamp of when the problem occurred
• The exact wording of the error messages
• The problematic file (if relevant)