Troubleshooting and FAQ

The quickest guide to the bumps we actually hit in the wild.

Install failures

ModuleNotFoundError: No module named 'aiohttp'

slack-sdk's async client imports aiohttp, and older environments do not pull it in automatically.

Fix. Activate the virtual environment and install it explicitly:

source backend/.venv/bin/activate
pip install aiohttp

It is also pinned in backend/requirements.txt, so a clean pip install -r requirements.txt on a new machine should not hit this.

tectonic: command not found

The LaTeX to PDF step uses the tectonic engine. If it is missing, the initial report generation will fail at the compile step.

Fix. On macOS:

brew install tectonic
tectonic --version

On Linux, use the official installer from the tectonic docs.

matplotlib fails to build from source

Usually a missing system compiler.

Fix. On macOS run xcode-select --install. On Debian/Ubuntu install build-essential. Retry the pip install -r requirements.txt step.

Running the backend

Backend starts but Slack never connects

If you see INFO: Uvicorn running on http://127.0.0.1:8000 but no Slack bot connected as ... line, the Slack tokens are probably wrong.

Fix. Double-check SLACK_BOT_TOKEN (starts with xoxb-) and SLACK_APP_TOKEN (starts with xapp-). Regenerate the app-level token if you are unsure. Also make sure SLACK_ENABLED=true.

Uvicorn reloader loops forever

This usually happens when the reloader picks up writes inside backend/reports/ or backend/test_outputs/. Every new PDF triggers a reload.

Fix. Restart uvicorn without --reload for longer sessions, or add --reload-exclude for the noisy folders.

Report generation

A report was not generated

The log shows Phase 1: Memory Agent but never Phase 2-F: Fraud Orchestrator. That means the intent classifier did not tag the message as fraud_analysis.

Fix. Rephrase the request to include the word "report" explicitly. "Generate a fraud intelligence report" is more reliable than "What is going on with fraud this month?".

The PDF uploaded but the log shows no fraud_reports row

This can happen if the initial generation failed silently at the persistence step. Inspect backend/test_outputs/<run_id>/run.log for any Failed to persist fraud_reports row message.

Fix. The PDF is still valid and viewable in Slack, but follow-up Q&A and edits will not work for that thread. Ask PyGuard to generate a fresh report in a new thread, and the row will land correctly.

Follow-ups and edits

PyGuard is making a brand-new report instead of answering my follow-up

This is the most common beta-release gotcha. You probably sent a new top-level message in the DM or channel rather than replying inside the thread where the PDF was uploaded.

Fix. Open the thread where the PDF lives (there is usually a "Thread" link under the PDF message) and type your follow-up there. The incoming thread_ts will match the row in fraud_reports, Phase 0 will fire, and you will see === PHASE 0: REPORT FOLLOWUP (report_id=...) === in the backend log.

The LaTeX edit failed

If tectonic cannot compile the edited tex, PyGuard automatically restores the previous tex and PDF from history/v{n}/ and replies with a short error plus the tectonic stderr tail.

Fix. Read the stderr tail, it is usually an unbalanced environment or an escaping problem. Reword the edit request to be smaller and more targeted. replace_text edits are the safest — they only change an unambiguous substring.

The edit applied but no new PDF appeared in Slack

If fraud_reports.version did not bump, the edit never wrote anything and Slack upload was skipped.

Fix. Read the backend log. If you see no edit applied, the editor agent did not call apply_edits_and_recompile — typically because the edit request was too vague. Try again with something specific like "rewrite the executive summary to focus on chargeback exposure".

Data questions

I uploaded a new CSV but PyGuard is still quoting old numbers

The FraudDataService lazily imports docs/fraud_dataset/fraud_dataset.csv on first SQL call and caches the rows in pyguard.db. It does not re-read the CSV.

Fix. Stop the backend, delete backend/pyguard.db (or drop the fraud_transactions table), and restart. The data will be reloaded on the next SQL call.

I want to ask about the current dataset, not what the report saw

The Q&A agent draws a line between "as of the report" (the saved snapshot) and "currently" (live SQL). Ask explicitly:

What does the live data currently show for chargeback rate?

The agent will call get_fraud_summary instead of read_data_snapshot.

Website and deploy

Vercel build fails with "No Next.js config found"

The Root Directory on Vercel is not pointing at PyGuard/website.

Fix. Open the project on Vercel, Settings → General, set Root Directory to PyGuard/website, and redeploy. Every content file lives inside that folder.

Mermaid diagrams do not render

Mermaid is rendered in the browser, not on the server. If they never appear, check the browser console for a CSP or script-blocking error.

Fix. Make sure no ad-blocker is stripping the Mermaid runtime. The diagram source is always visible in the DOM even when rendering fails, so the page is never blank.

Ready to file an issue?

If none of the above match what you are seeing, please file a bug report — it genuinely helps the beta. The Contribute page has a button that opens the GitHub bug report template with the right labels pre-filled.