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

Parsing & generation

Symptom	Fix
No requirements extracted	Need # Title + ## Acceptance Criteria with concrete paths — Writing Good Specs
Generated tests all hit /	Template fallback; add paths or configure LLM
NL parsing failed	create needs an LLM key
No valid Playwright specs	Quality gate failed — delete bad tests/generated/ and regenerate

Execution

Symptom	Fix
Timeouts on networkidle	Often swallowed; check ZYVOR_BASE_URL / nav timeout
Pass locally, fail in CI	Different URL/env; check artifacts; CI uses workers: 1

Regression

Symptom	Fix
No baseline for …	make regression-update
Noisy diffs	Animations/timestamps; raise threshold carefully; recapture after viewport change

Still stuck?

Configuration · Security and Target Policy · Deploy and Releases · Enterprise · issues