Troubleshooting
| Symptom | Cause and fix |
|---|---|
| “PersonaQA is still installing the browser” | The first session after install downloads Chromium in the background. Wait a minute and run again. Progress is in ~/.claude/plugins/data/personaqa-persona-qa/setup.log |
“Chromium is not installed yet” and setup.log shows an error | The download failed (often a proxy). Start a new session to retry. On Linux, also run npx playwright install-deps chromium once (needs sudo) |
| “No config found … Run /personaqa:init first” | Run /personaqa:init in the repository root, or open Claude Code in the folder that holds .personaqa/ |
| “environment variable X is not set” | The config uses ${X}; export it, or give a default with ${X:-value} |
| “Mission start URL … is outside app.allowed_domains” | Add the host (with port, if it has one) to app.allowed_domains |
| Personas say a page is blank or a link “did nothing” | The page needs a host that is not in allowed_domains (an API, a CDN, a payment form). The run’s run.json lists blocked_requests |
| “No saved login at …” | Run /personaqa:auth, or see Logins for sites with single sign-on or two-factor codes |
| Personas land on the sign-in page | The saved login has expired. Run /personaqa:auth again |
Every session ends as limit | Steps or minutes ran out. Read a journal first: the journey may be genuinely too long or confusing. Otherwise raise max_steps or time_limit_minutes on the mission |
| A session succeeds immediately | The mission’s success rule already passes on the start page; make it more specific. See Missions |
| A finding is wrong or accepted | /personaqa:report dismiss ISSUE-n "reason"; later runs hide it |
| The report has no Download PDF button | Exporting needs the plugin’s browser. Run /personaqa:report export to see the error |
| Emoji show as boxes in screenshots | The headless browser has no emoji font. It does not affect what personas do or see in text |
| Runs cost more than expected | Use fewer personas on pull requests, runner.model: haiku, lower max_steps_per_run, and screenshots: on_issue. total_cost_usd in claude -p --output-format json is the API-rate cost; on a Pro or Max plan runs use your allowance instead. See Cost and usage |
Still stuck? Open an issue on GitHub with the run’s run.json and actions.log (remove anything sensitive first).