Troubleshooting

Most build failures relate to TeX environment or missing packages. This guide covers common issues and solutions symptom-by-symptom.

Diagnostic Commands

Open Terminal and run:

which lualatex which latexmk which latexindent which synctex

Also check in TeX64: Settings > Runtime tab to verify environment status

TeX Environment Issues

"latexmk not found"

Cause: TeX distribution not installed or not in PATH

Fix:

  • Install MacTeX from https://www.tug.org/mactex/
  • Or: sudo tlmgr install latexmk
  • Verify: which latexmk
  • Restart TeX64 after installing

"lualatex not found"

Cause: TeX distribution not installed

Fix: Install MacTeX (includes lualatex)

"latexindent not found"

Fix:

sudo tlmgr install latexindent

Note: latexindent is optional (for code formatting), build works without it

"synctex not found"

Fix: included in MacTeX by default, or: sudo tlmgr install synctex

Without synctex, SyncTeX navigation won't work

Missing .sty Package

Error: "File xxx.sty not found"

Fix:

sudo tlmgr install <package-name>

To search:

tlmgr search --global --file <filename>

PATH Issues

Check: echo $PATH

Should include /Library/TeX/texbin for MacTeX or /opt/homebrew/bin for Homebrew

Fix: Add to ~/.zshrc: export PATH="/Library/TeX/texbin:$PATH"

Restart Terminal and TeX64

Build Issues

Build Fails with Errors

Check build output panel for error messages. Click on error to jump to source line.

Common causes: typos in LaTeX commands, mismatched braces, missing packages

Tip: Use AI (Axiom) to diagnose - paste the error or ask in chat

PDF Not Updating

PDF only updates on SUCCESSFUL builds. Check build output for errors.

Rebuild with Cmd+B.

Build is Slow

Large projects with many images take longer.

latexmk uses incremental compilation - second builds are faster.

First build may be slow due to package downloads

SyncTeX Issues

SyncTeX Not Working

Verify synctex is installed: which synctex

Rebuild the project (Cmd+B) to generate .synctex.gz file

Verify green checkmark in Settings > Runtime

SyncTeX Jumps to Wrong Location

Some LaTeX packages interfere with source mapping

Multi-file projects: ensure \input/\include paths are correct

macOS Issues

Gatekeeper

Control+click (right-click) → Open Or: System Settings > Privacy & Security > Allow

Screen Recording Permission (for OCR)

System Settings > Privacy & Security > Screen Recording > enable TeX64

May need to restart TeX64 after granting permission

"App is Damaged"

Re-download the DMG. Verify correct architecture (Apple Silicon vs Intel)

AI/Axiom Issues

AI Features Not Available

Check subscription: Account > Billing

Free plan does not include AI features

Check token quota: Account > Usage

Verify internet connection

AI Responses Slow or Timeout

Check internet connection

Server may be under load - try again in a moment

Rate limit: 30 requests/minute

Agent Mode Not Available

Agent mode requires Pro plan ($25/month)

Account & Login

Google Login Fails

Check internet connection. Try clearing browser cookies/cache. Try signing in again.

Subscription Not Reflecting

Billing changes may take a few minutes

If payment failed, update payment method via Stripe billing portal

Grace period: 3 days after payment failure before features are disabled

Gallery Issues

Post limits: Free=10, Basic=100, Pro=500

Daily post limit: 10 per day

Image size: 20MB max. TeX source: 500,000 chars max. Tags: 8 per post max.

Getting Help

Use AI chat to describe issues (it can read compile logs)

Contact support at /feedback

Include: macOS version, TeX64 version, error message, steps to reproduce

Optional error diagnostics can be enabled in Settings > Privacy

Tip: When diagnosing build issues, start by running diagnostic commands to verify your TeX environment setup. Most issues stem from environment problems.