Troubleshooting

Troubleshooting

Common failures and fixes. Full doc: troubleshooting.md. Short FAQ: FAQ.

Install & environment

Symptom	Fix
zyvor-qa: command not found	make install / pip install -e ".[dev]"; activate venv; which zyvor-qa
Playwright “Executable doesn’t exist”	npx playwright install --with-deps chromium (or full browsers)
Python version errors	Need ≥ 3.10 (3.11+ recommended)

Prefer the GHCR image in CI so browsers are prebundled — External CI/CD.

GitHub

Symptom	Fix
Token required	gh auth login or GITHUB_TOKEN in .env
Expired CLI token	gh auth refresh -h github.com
ZYVOR_PRODUCT_REPO is not set	owner/repo form, not a URL
Fetch 404	Repo visibility, path, or token scope (Contents: Read)

See GitHub Integration.

Target / SSRF policy

Symptom	Fix
Target rejected by policy	ZYVOR_ENV=development or production + ZYVOR_TARGET_ALLOWLIST=hostname
Login tests on zyvor.dev	Keep ENABLE_DASHBOARD_TESTS=false (no product login)

LLM / create

Symptom	Fix
create / AI cmds fail immediately	Set LLM_PROVIDER + matching API key (or Ollama)
Bad generated TS	Quality gate falls back to template; rephrase AC / NL prompt

Dashboard / serve

Symptom	Fix
Exposed without auth	Set DASHBOARD_PASSWORD before network exposure
Webhook 401	Match GITHUB_WEBHOOK_SECRET; require X-GitHub-Delivery in enterprise mode
.env in product CI ignored	Expected — pass env/secrets only

Autofix / regression

Symptom	Fix
Wrong selector patched	Review git diff; use suggest-only (ENABLE_AUTOFIX_APPLY=false) in CI
Visual flaky	Raise REGRESSION_THRESHOLD carefully; stabilize animations; commit baselines deliberately

Reports

Look in reports/qa-summary.html, reports/summary.json, test-results/, and npm run report.

Still stuck?

Configuration · Deploy and Releases · Enterprise · open an issue on ZyAIQAAgent