Resolve a failed compile

About this guide

These instructions describe the desktop application and its configured services. For the hosted browser editor, start with the AtruhaTeX Web guides above. Desktop menu names and service settings may differ from Web.

Read Issues and the original message

Switch the preview pane from PDF to Issues. Read what happened, follow the affected file and line, and expand the original diagnostic when you need the compiler’s exact wording. Fix one established cause, save, and compile again. A visible last-good PDF may belong to an earlier successful run; check the latest attempt and preview status.

Check engines, packages, and fonts

If a compiler is unavailable, inspect tools in Settings → About and install the missing TeX distribution or executable. If a package is missing, check its name in the log and install it through your TeX distribution. For fontspec or unsupported Unicode errors, select XeLaTeX or LuaLaTeX and a font that supports the script. Changing the app’s interface font does not change the document’s publication font.

Apply only a relevant fix

Auto fix appears only for verified, unambiguous missing-package cases. It checks that the source still matches the compile snapshot and saves recovery before adding a minimal, undoable package declaration. Syntax, layout, bibliography, and reference problems can require manual changes. If the document changed after compilation, compile again or inspect the source before applying a proposed fix.

Check permission and working context

A project awaiting execution permission cannot compile automatically or manually until the decision is reviewed. If isolated execution is selected but its configured runtime is missing, the app stops instead of silently switching to local execution. In a browser workspace, native compilation and previews are unavailable. Use the desktop app and review the project’s actual permission and tool requirements.