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:
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:
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:
To search:
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