Troubleshooting

Troubleshooting

Start with .venv/bin/python -m app selftest and the run's log on the Runs page; most problems name themselves there.

Symptom	Cause and fix
FAIL Claude: ... in selftest	No Claude access. Log in (claude → /login), or set ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN. See Claude Access.
MISSING lualatex / xelatex	TinyTeX is not on PATH or not in ~/.TinyTeX. See SETUP.md section 1.
MISSING bun	Install bun and open a new shell.
A search finds nothing new	Every job was already seen (job_scraper/seen_jobs.json) or filtered. The log shows the count after each step: scraped, new, triage, size, scored.
"too small" for a company you know is large	The size lookup was wrong or stale. Delete its entry from app/data/company_sizes.json and run again.
linkedin '...' failed	The LinkedIn CLI hit a limit or changed. Other sources still run; try again later.
Drafts land in Needs review	A check failed after compiling (CV not 2 pages, letter not 1 page, orphaned heading, banned name). The reason is in the row's notes. Fix the .tex and recompile with python3 app/texc.py cv/main_<slug>.tex, or Skip it.
A draft says EXPIRED or VETO in the log	The posting was closed, or broke a deal-breaker; nothing was drafted.
Check email says Gmail is off	Add your Gmail address and app password in Settings and turn on Check Gmail.
Gmail login failed	Use an app password, not your Google password; 2-Step Verification must be on.
A reply was not picked up	It was older than the first 180-day pass, or it read as recruiter outreach or a job alert. To re-read everything see Gmail Tracking.
The dashboard logged me out	Sessions live in memory, so a restart signs you out. Sign in again.
"already queued or running"	The same task is running; watch it on Runs or cancel it there.
Phone alerts don't arrive	Notifications on, same topic in the ntfy app, then Send test notification.
Docker: TeX sandbox errors	bubblewrap needs the bundled seccomp profile (app/deploy/seccomp-bwrap.json); keep security_opt from the compose file.
Port 443 in use	Change the router ports in app/docker-compose.yml.

Still stuck? Open an issue with the run log, after removing personal data.