Help

Troubleshooting

Every command ends with a line like Result: repair-failed (validation-failed): the outcome, then the reason code in brackets. The record path printed after it has the full detail.

Outcomes

Outcome	Meaning	Exit
`diagnosed`	At least one cause is supported by the evidence.	0
`inconclusive`	The evidence doesn't support a cause, or the run couldn't be analyzed.	0
`proposal-ready`	A repair was proposed with `--propose-only`.	0
`repair-declined`	You declined a request or the patch.	0
`abstained-from-repair`	KwikQA chose not to repair, for the reason given.	0
`awaiting-validation`	The patch is applied. Run `validate`.	0
`repaired`	Validation passed and the patch was kept.	0
`repair-failed`	Validation failed and the patch was rolled back.	1
`validation-unavailable`	The repair couldn't be validated, so it wasn't kept.	1
`operation-failed`	Something outside the normal flow failed. See the reason code.	1

Common reason codes

Reason	What to do
`report-unavailable`	No report was found. Add the reporter for your framework, or pass `--report` with a report file or directory.
`report-unreadable`	The report isn't one KwikQA reads, or it is incomplete. KwikQA reads Playwright JSON, its own Cypress and WebdriverIO reporters, mochawesome, `@wdio/json-reporter`, and JUnit; a JUnit report that doesn't name its framework needs `--framework`. Rerun the tests so the reporter writes the report in full.
`no-failures`, `zero-tests`	The report has nothing to diagnose.
`interrupted-run`, `report-errors`	The run didn't finish cleanly, so its evidence isn't trustworthy. Fix the run, then analyze again.
`evidence-budget-exceeded`	The evidence wouldn't fit the packet size limit. Analyze a report with fewer failures.
`remote-consent-declined`	You declined the preview. Nothing was sent.
`application-owned`, `environment-owned`	The evidence points outside your tests. Use the diagnosis to investigate; no repair is proposed.
`repair-config-missing`, `repair-config-invalid`	Run `npx kwikqa init`, or fix `kwikqa.config.json` using the message.
`repository-status-unavailable`	KwikQA couldn't read git status. Run it inside the git repository, with git installed.
`original-test-ambiguous`	The failing test couldn't be identified uniquely. Analyze a report with fewer failures.
`validation-scope-unavailable`	KwikQA couldn't work out which tests the change affects, so it didn't apply the patch. The message says why.
`baseline-capture-unavailable`	The repair changes shared test code, which 0.1 can't validate yet. See the known limitation.
`application-rejected`	KwikQA couldn't prepare or apply the patch safely, for example because a target file changed. The message says why; run `fix` again.
`application-recovery-required`	KwikQA found patch records in `.kwikqa/` it can't reconcile. The message names the problem; check the patched files with `git diff` before you continue.
`no-pending-repair`	There is no applied patch to validate. Run `fix` first.
`validation-incomplete`	A required check was skipped, interrupted, or didn't produce fresh results. The patch was rolled back.
`rollback-conflicted`	You edited a patched file after KwikQA applied it, so rollback stopped instead of overwriting your work. Review the file by hand.
`no-retry-available`	The one retry was already used. Fix the test by hand.

Common messages

Not signed in. Run npx kwikqa login first.: Sign in, or set KWIKQA_TOKEN. In CI, check that the secret is passed to the step.
You have used all … on the … plan: You've reached a monthly limit. See Plans and usage.
Sending evidence needs approval: There is no terminal to approve the preview. Pass --yes, or use --local.
kwikqa fix needs a terminal: Applying a patch needs a person. Run fix locally, or, in GitHub Actions, Azure Pipelines, or GitLab CI/CD, commit a ci.fix policy so it opens its repair as a draft pull request.
kwikqa.config.json differs from its committed version: kwikqa fix in CI runs only under the policy as committed. Commit the change, and don't edit kwikqa.config.json in the job.
No fix in CI: …: Before sending anything, kwikqa fix found it couldn't open a fix pull request: a fork's pull request, a run on a tag, or a missing token. The text says which, and nothing was charged.
Fix pull request #… is already open for it: A fix for this failure is in review, so no repair was asked for; the run is noted on it. Merge or close it. A closed fix's kwikqa/fix- branch also holds the failure back until you delete it.
The BYOK plans need OPENROUTER_API_KEY: Export your OpenRouter key in the shell that runs KwikQA.
No pull-request comment: … / No merge-request note: …: In CI, KwikQA couldn't publish its comment. The text after the colon says why, most often a token's missing permission, and the build isn't affected. Running in CI lists what each CI system needs.
Slack or Teams got no message: KwikQA posts only when tests failed, unless you pass --notify always. It treats an empty webhook variable as unset, so check that the secret has a value and is passed to the step.
Resolved package files are outside the repository: Your Playwright, Cypress, or WebdriverIO is installed outside the git repository, for example in pnpm's global virtual store. KwikQA runs your test runner only from inside the repository: install your dependencies into it, and run KwikQA from inside it. See Monorepos.

Still stuck? Contact support.