Common fixes.

macOS says the app cannot be opened

The early build is ad-hoc signed. Right-click DraftPilot, choose Open, then confirm.

Linux AppImage asks for FUSE

Install FUSE on the Linux desktop, or use the CLI binary for VM/headless workflows.

PDF/source jump says SyncTeX is missing

Run a clean build with SyncTeX enabled. DraftPilot uses latexmk -synctex=1 during normal builds.

VM launch cannot find DraftPilot

Install DraftPilot on the VM or pass --app-dir to a VM directory containing the DraftPilot binary or source checkout.

Port already in use

draftpilot status --port 4179
draftpilot stop --port 4179
draftpilot launch --paper /path/to/paper --port 4180

LaTeX build fails

Check the Logs panel and use Fix Build when DraftPilot shows a build error. For terminal diagnostics, run:

draftpilot logs --tail 160
draftpilot doctor --paper /path/to/paper --codebase /path/to/codebase

Installer or launch fails

Run doctor first and keep the exact error message. Most setup failures are missing LaTeX tools, a PATH that does not include DraftPilot yet, an unavailable port, or a VM that cannot see the remote paper/codebase paths.

draftpilot version
draftpilot doctor --paper /path/to/paper --codebase /path/to/code
draftpilot launch --paper /path/to/paper --codebase /path/to/code --port 4180

From the app, open Settings/About and export a safe support bundle. It excludes paper content, paths, comments, highlights, PDFs, and logs by default.

Install LaTeX tools

DraftPilot compiles locally, so the machine running DraftPilot needs a TeX distribution and latexmk.

brew install --cask mactex-no-gui
eval "$(/usr/libexec/path_helper)"

sudo apt update
sudo apt install texlive-latex-extra texlive-fonts-recommended latexmk

sudo dnf install texlive-scheme-medium latexmk

winget install MiKTeX.MiKTeX
miktex packages update