Setting Up LaTeXDaemon for Continuous LaTeX Builds

Troubleshooting Common LaTeXDaemon Errors

LaTeXDaemon automates LaTeX compilation and continuous builds for projects. When it fails, builds can stall or produce confusing logs. This guide walks through the most common LaTeXDaemon errors, how to diagnose them, and practical fixes to get your automated LaTeX workflow back on track.

1. Build never starts (watcher not triggering)

Symptoms: File changes don’t start a compile; daemon appears idle. Likely causes & fixes:

• Filesystem watcher limits: On Linux, inotify limits may be too low. Increase them:
  • Temporarily: sudo sysctl fs.inotify.max_user_watches=524288
  • Permanently: add fs.inotify.max_user_watches=524288 to /etc/sysctl.conf and run sudo sysctl -p.
• Ignored paths or globs: Check LaTeXDaemon config for exclude patterns (e.g., node_modules, .git) accidentally matching your source folder. Remove or refine excludes.
• Daemon not running under expected user: Ensure the service runs with permissions to see your files. If started as a different user, restart it under your user or adjust file permissions.
• Editor saves to temp file then renames: Some editors (e.g., Atom, VS Code with certain settings) write temp files and rename, which might not trigger watcher. Disable atomic saves or configure LaTeXDaemon to follow renames if supported.

2. Compilation starts but fails immediately with “command not found” or PATH issues

Symptoms: Log shows shell error like pdflatex: command not found or TeX engines not found. Likely causes & fixes:

• TeX distribution not installed or missing engine: Install a TeX distribution (TeX Live, MiKTeX) or add needed engines (xelatex, lualatex).
• Daemon’s PATH differs from your shell: Services/daemons often have a limited PATH. Provide full paths in LaTeXDaemon config (e.g., /usr/bin/pdflatex) or set PATH explicitly in the service unit (systemd) or startup script:
  • systemd example: add Environment=“PATH=/usr/local/bin:/usr/bin:/bin” in the unit file and restart the service.
• Permissions preventing execution: Ensure the daemon user can execute the engine binaries (ls -l $(which pdflatex)).

3. Missing packages or fonts reported during compile

Symptoms: LaTeX log shows “file xxx.sty not found” or font substitution warnings. Likely causes & fixes:

• Incomplete TeX distribution: Install missing packages via your distribution’s package manager:
  • TeX Live: use tlmgr install (if using full TeX Live, consider installing scheme-full or at least scheme-small + needed packages).
  • MiKTeX: use MiKTeX Console or mpm –install .
• Daemon running in restricted environment: If the daemon runs in a container or isolated environment, ensure the container image includes required packages/fonts.
• Local package paths not visible: If you use a local texmf tree, ensure TEXMFHOME/TEXMFLOCAL settings are visible to the daemon. Set TEXMFHOME in environment or LaTeXDaemon config.

4. PDF not updating or stale output

Symptoms: Compiler runs successfully but the generated PDF viewed elsewhere is unchanged. Likely causes & fixes:

• Output written to unexpected directory: Check output directory settings (e.g., -output-directory=build). The viewer may show an older PDF from a different path. Adjust viewer to the correct file.
• Race condition with viewer locking file: Some PDF viewers lock files (especially on Windows). Configure the viewer to auto-reload or use a viewer that supports file-reload (e.g., SumatraPDF on Windows, Skim on macOS with auto-reload).
• Caching in web UIs or CI artifacts: When using web-based