LuaBill · Documentation

Troubleshooting LuaBill

Start with the first specific error in the generation log. It usually explains more than the final failure message.

LuaLaTeX cannot create the PDF

Open the Generation log tab and note the retained work folder. Read pass1.txt and document.log, starting at the first error. A missing .sty file, font, format or language resource can stop compilation even when LuaLaTeX itself is installed.

Run Help → Prepare document creation again for your format. You can also download the LaTeX check file from the Download page and compile it with your TeX distribution. MiKTeX may install missing packages when configured to do so; TeX Live packages must be managed through the matching TeX Live or operating-system package manager.

  • A LuaHBTeX version banner is normal for LuaLaTeX; invoke lualatex rather than replacing it with luahbtex.
  • Restart LuaBill after changing PATH or installing document tools.
  • Use Help → Components and installation to rescan tools and open official download links.
Component requirements and LaTeX check →

XML or ZUGFeRD validation fails

Check the selected document type and output format, then read the exact validation message. Common causes include incomplete structured addresses, missing electronic endpoints or buyer reference, inconsistent VAT treatment and incomplete advance-payment details.

Correct the source project and generate again. Do not repair a single exported amount by hand while leaving the PDF or project inconsistent. Help → E-invoice standards and updates shows installed versions and can check official releases; the local audit files identify the rules used for that document.

XRechnung data and reports →ZUGFeRD packaging and validation →

Find projects, output and moved images

The .luabill file is your editable project; PDF/XML files are generated results. The output folder is a per-user application setting. Use the result panel's Open PDF, Open XML or Open output folder buttons after successful generation.

When moving a project to another computer, also copy any custom signature and stamp images and select their new locations. Interface language and output preferences stay local. Opening an unchanged document should not create an unsaved-change warning; offer validity is generated from the document fields without appending hidden editable rows.

When reporting a problem, include the LuaBill version, operating system, selected output format and the first relevant error. Review logs and sample documents for confidential customer, tax or payment details before sharing them.

Contact the authors →Check the application release notes →
← Back to documentation

Before you start

Is LuaBill free for business use?

Yes. LuaBill's own code and documentation are available under Apache License 2.0, including for commercial use under its terms. There is no LuaBill subscription. Third-party components keep their original licenses.

Do I need to know Lua or LaTeX?

No. The graphical form handles ordinary editing. LuaLaTeX must be installed, but you do not need to write LaTeX commands to fill in the structured fields. Developers can adapt the source and templates.

Do I have to install a complete TeX distribution?

No. On Windows, the setup wizard can install Basic MiKTeX and the packages required by LuaBill. It keeps the application download compact, but preparing missing document tools still requires Internet access and additional downloads. Linux distribution packages may group more fonts and packages together; the macOS Homebrew route uses BasicTeX plus the required additions. Existing suitable TeX installations are reused.

Can I include LaTeX formulas in a business document?

Yes. Remarks supports a restricted set of LaTeX commands for text emphasis and formulas, including integrals, sums and fractions. Enclose mathematics in \( ... \) or \[ ... \]; ordinary text needs no markup. PDF renders the formulas. In XML-exported notes, the LaTeX source remains plain text and is not automatically rendered by the recipient. Introductory text is PDF-only. Arbitrary packages and macros are not supported.

Are my customer and invoice details uploaded?

LuaBill generates documents locally and does not upload invoices to a generation service. Clicking Check in VIES sends the customer VAT ID to the European Commission’s VIES service. Component preparation downloads software, packages and fonts. A requested or enabled weekly update check reads public release metadata without sending invoice, customer or XML data. You control how the finished invoice is sent.

How does the VIES check and green VAT mark work?

Enter the complete EU VAT ID with its country prefix (XI for Northern Ireland, EL for Greece), then click Check in VIES in Customer. A completed reply records the result and date; save the .luabill project to retain them. A negative reply removes the green mark. Service or connection errors leave the previous record unchanged. The chosen validity period is counted in calendar days relative to today, and to the generation day for PDF; the invoice date does not affect it. VIES does not check the customer’s name or address here or establish the tax treatment of the transaction.

Can I invoice customers outside Germany?

The current version supports sellers based in Germany and customers in Germany, other EU countries or outside the EU. Select the actual transaction scenario and delivery country; a foreign customer alone does not establish a VAT exemption.

Can I use USD, RUB or CNY?

Yes. Choose a currency code independently of the customer's country. LuaBill does not perform exchange-rate conversion. The payment QR code is for eligible EUR/SEPA invoices; electronic monetary totals support at most two decimal places.

Does a ZUGFeRD PDF need a separate XML attachment in my email?

The hybrid PDF already contains the XML. Normally that PDF is sent as the invoice; the recipient may have additional requirements. XRechnung, by contrast, is submitted as its XML file, not just the PDF view.

Where are my projects and results stored?

The initial suggestions are Documents/LuaBill/Projects and Documents/LuaBill/Output. You can choose other folders. The output location is a preference for your user account on that computer; it is not stored as a fixed path in every project.

Are all three operating systems equally tested?

A Windows installer is available with Python and Qt included. Linux and macOS packages install from source and are currently previews: their native installation and graphical launch still need verification on those operating systems.

Is this a complete accounting or tax system?

LuaBill focuses on preparing business documents. It does not replace bookkeeping, tax advice, a legally assessed archive or the controls for your invoice-number sequence. Quotations and orders remain PDF business documents, not electronic invoices.

How do I check a failed generation?

Read the first compiler error in the Generation log or the invoice validation report. Use Help → Prepare document creation to verify the tools and create a sample; the wizard can open its log folder and copy diagnostic details. The standalone LaTeX test below also helps identify a missing package or font.

Should I uninstall LuaBill before updating?

No. Close LuaBill and run the new installer into the same folder. On Linux/macOS, reuse your custom --prefix. Personal projects, results and preferences remain in place. Save manual program-file edits separately; the Unix installer stops on a conflicting file.

Why does LuaLaTeX report LuaHBTeX?

A “This is LuaHBTeX” version banner is normal: LuaLaTeX uses that engine in TeX Live. The command should remain lualatex, and texlua also needs its own launch name. LuaBill 0.1.14 and newer preserve these aliases correctly. Use the current package rather than replacing lualatex with a direct luahbtex command.

Where can I see which rules checked my invoice?

Open Help → E-invoice standards and updates, or click Validation versions beside the generated result. The audit separates the active rules from older resources inside the original Mustang JAR. Keep the .validation-info.json file and both XML validation reports with the issued document; they identify the checked profile, rule versions, hashes and stage results.

Does LuaBill check for changes to invoice rules automatically?

Use Check for updates in the standards dialog, or enable the optional weekly check when LuaBill starts. It is off by default. The check compares public technical releases and sends no invoice data; it does not install rules. A new release prompts review of a LuaBill update, not an automatic conclusion about legal deadlines or your recipient’s requirements.

Why are some files left after uninstall?

LuaBill deliberately preserves documents, preferences and modified or untracked files. Separately installed system tools and the downloaded package folder also remain. Read the uninstaller's warnings and remaining-file paths. The current archive's uninstaller can remove an earlier installation without reinstalling it.