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 plan the validation, so it didn't apply the patch. The message says why. For Java and Python messages, see the table below. |
not-a-browser-test | A Java, Python, or Cucumber-JVM failure is repaired only when its failing tests are end-to-end browser tests. A test in the group doesn't reach a browser library, or KwikQA can't confirm that it does, so the group is diagnosed and not repaired, and fix sends no repair request for it. The messages are in End-to-end browser tests. |
baseline-capture-unavailable | A repair to shared test code needs its affected tests to run on the current code first. The baseline wasn't approved, or it didn't finish with complete results for every affected test. The message says which. Nothing was applied; see the workflow. |
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. |
Java and Python validation
fix reports these messages as validation-scope-unavailable and doesn't apply the patch. check reports them as not checked, so its verdict is incomplete. The message names what is missing.
| Message | What to do |
|---|---|
| JAVA_HOME is not set | Java validation needs a JDK already on this machine, and KwikQA never installs one. Install a JDK, set JAVA_HOME to its absolute path, and run fix again. |
| JAVA_HOME must be an absolute path to a JDK | Set JAVA_HOME to the JDK's full path, not a relative one, and run fix again. |
| has no bin/java launcher, so it is not a JDK | The folder isn't a JDK. Point JAVA_HOME at the JDK's root folder, the one that holds bin/java, and run fix again. |
has no mvnw and mvn was not found on PATH, or the same for gradlew and gradle | The build has no wrapper, and Maven or Gradle isn't on your PATH. KwikQA never installs either. Add the project's wrapper, or install Maven or Gradle where your PATH finds it, and run fix again. |
mvnw is not executable, or the same for gradlew | The wrapper has no execute bit. Run chmod +x on it, and run fix again. |
| is missing or unreadable. KwikQA pins the wrapper's jar and properties, or must be a regular file inside the workspace | A wrapper file is missing, or it is a link. Restore the wrapper's .mvn/wrapper or gradle/wrapper files from version control, and run fix again. |
| The Maven wrapper's distribution … isn't in … and KwikQA never downloads one, or the same for Gradle | The wrapper hasn't unpacked its distribution, and KwikQA doesn't download it. Run ./mvnw --version (or ./gradlew --version) once yourself, then run fix again. KwikQA looks under MAVEN_USER_HOME or GRADLE_USER_HOME when they are set, and under ~/.m2 or ~/.gradle otherwise. |
| distributionUrl: the wrapper's properties name no or more than one, or the URL must be an https link to a distribution .zip | KwikQA can't tell which distribution the wrapper would download. Fix distributionUrl in the wrapper's properties file, and run fix again. |
| user home … must be an absolute path | MAVEN_USER_HOME or GRADLE_USER_HOME is relative. Set it to an absolute path, and run fix again. |
| Maven validation is unavailable on Windows, or the same for Gradle | Maven and Gradle wrappers and tools need a shell on Windows, which KwikQA doesn't start. Run Maven or Gradle validation on macOS or Linux. |
| No project virtual environment (.venv or venv) was found | pytest runs only from the project's own environment, never a global Python or pip, and KwikQA doesn't create one. Create .venv in the folder the message names, install the project's requirements into it, and run fix again. |
| has no executable bin/python, or has no pyvenv.cfg | The virtual environment is incomplete, or it was copied from another machine. Recreate it with python -m venv in that folder, and run fix again. |
| resolves outside the workspace | The .venv or venv folder is a link to a place outside the workspace. Replace it with a real virtual environment inside the workspace. |
| No Maven pom.xml or Gradle build file was found at or above, or No pytest configuration or conftest.py was found at or above | No build sits above the changed file, so KwikQA can't tell which build runs its tests. Check that the file is inside the project it belongs to, and run fix again. |
| The changed files lie in … different builds | KwikQA validates one build at a time. Split the change, so that each repair touches one build, and run fix again. |
| goes through a symbolic link, or isn't a directory in the workspace | The build folder is a link, or it lies outside the workspace. Use the real folder inside the workspace, and run fix again. |
| The tests a shared repair affects can't be known completely | KwikQA won't guess a smaller set of tests, so it doesn't apply the repair. The message names what it couldn't follow: a file it can't read or parse, a lookup by name such as Class.forName, ServiceLoader, importlib, or getfixturevalue, a usefixtures name that isn't a string literal, or a pytest_plugins or pythonpath value KwikQA can't read. Make the reference a plain import or a literal name, or fix the file, and run fix again. The pytest_plugins and pythonpath reasons are explained in End-to-end browser tests. For a size limit, KwikQA can't validate the repair in that project, since there is no smaller set to fall back on. |
End-to-end browser tests
For a Java, Python, or Cucumber-JVM failure, fix repairs a group only when every failing test in it reaches a browser library, through the project's code or a browser plugin that its environment installs. Otherwise it prints the reason on its result line: Result: inconclusive (not-a-browser-test), or Result: abstained-from-repair (not-a-browser-test) when --group names the group. analyze still diagnoses the group and offers no repair for it. check reports a change to such a test as not checked, and the verdict is incomplete unless another gate fails.
The message has one of these two forms. <test> is the test's titles, outermost first and joined with >, such as CartTest > addsTax. <libraries> is Selenium, Selenide, Appium, or Playwright for Java and Cucumber-JVM, and Selenium, Playwright, Appium, SeleniumBase, or Splinter for Python. In a check message, the last clause reads so the change to it isn't checked.
| Message | What to do |
|---|---|
| KwikQA repairs end-to-end browser tests only. `<test>` reaches no browser library (<libraries>) through its own code, so it's diagnosed, not repaired. | KwikQA followed the test's references and found no browser library, so it treats the test as a unit test: it diagnoses the failure and offers no repair. Fix the test by hand. If the test drives a browser through a pytest plugin's fixture, such as page or driver, install that plugin into the project's .venv. KwikQA counts a plugin's fixture only when the environment installs the plugin. |
| KwikQA repairs end-to-end browser tests only, and it couldn't confirm that `<test>` reaches a browser library (<libraries>) through its own code: <reasons>, so it's diagnosed, not repaired. | Each reason below says what KwikQA couldn't follow or check. Make the reference a plain import or a literal name, or install the browser plugin into the project's .venv (or venv). Then run analyze and fix again. |
Reasons are separated by semicolons. Some of them also appear in the message for a shared repair, The tests a shared repair affects can't be known completely, which Java and Python validation lists.
| Reason | What to do |
|---|---|
| <file> loads code or fixtures by name, which KwikQA can't follow. | Replace the lookup with a plain import or a literal name. In Python, the lookups are importlib, __import__, getfixturevalue, indirect=, lazy_fixture, and a usefixtures mark whose names aren't string literals. In Java, they are Class.forName and ServiceLoader. |
| <file> sets pytest_plugins to a value KwikQA can't read, so the plugins it loads are unknown. | Make pytest_plugins a literal: a string, or a list or tuple of strings, each a dotted Python module name such as "plugins.fixtures". Don't build it from variables, calls, or f-strings, and don't use the name anywhere else, such as in config.pytest_plugins. |
| <config>'s pythonpath can't be read, so KwikQA can't tell which directories it searches.; or, for one entry, <config>'s pythonpath entry "<entry>" leaves the workspace, so KwikQA ignores it., with goes through a symbolic link or can't be inspected in place of leaves the workspace for the other two cases | The message follows an import that KwikQA can't resolve, shown as Import <module> isn't found in <file>'s own directories or their ancestors. KwikQA reads pythonpath from the first of these that holds pytest's settings in the build's folder: pytest.ini, .pytest.ini, pyproject.toml's [tool.pytest.ini_options], tox.ini's [pytest], or setup.cfg's [tool:pytest]. Write its value once, as plain paths with no $, %, ~, *, ?, brackets, braces, or backslashes. In an INI file, also leave out quotes, #, and ;. Point each entry at a folder inside the workspace that isn't a link. |
No project virtual environment (.venv or venv) was found at <where>, so KwikQA can't tell whether pytest-playwright, pytest-selenium, SeleniumBase, or pytest-splinter is installed.; or, for a .venv or venv that is there, <venv> in <where> holds no site-packages, so KwikQA can't tell whether pytest-playwright, pytest-selenium, SeleniumBase, or pytest-splinter is installed., or <venv> in <where> is not a directory, so KwikQA can't tell whether pytest-playwright or pytest-selenium is installed. | A pytest fixture from a browser plugin counts only when the project's own environment installs that plugin. Create the .venv (or venv) folder the message names, or repair it, install the project's requirements and the browser plugin into it, and run analyze and fix again. <where> is the workspace root or the build's folder. |
| The step definition class <class> isn't in the workspace's source roots, so the scenario's browser use is unknown., or The step definition class <class> is in <n> workspace files, so the scenario's browser use is unknown. | Keep each step definition class in one file, under a source root KwikQA reads, such as src/test/java. Then run analyze and fix again. |
Common messages
- Not signed in. Run
npx kwikqa loginfirst. - 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.
- Not diagnosed: …
- A plan rule refused this CI run, so it was analyzed locally, and nothing was counted. The message names the rule and what to do. Running in CI lists each message.
- Sending evidence needs approval
- There is no terminal to approve the preview. Pass
--yes, or use--local. kwikqa fixneeds a terminal- Applying a patch needs a person. Run
fixlocally, or, in GitHub Actions, Azure Pipelines, or GitLab CI/CD, commit aci.fixpolicy so it opens its repair as a draft pull request. - kwikqa.config.json differs from its committed version
kwikqa fixin CI runs only under the policy as committed. Commit the change, and don't editkwikqa.config.jsonin the job.- No fix in CI: …
- Before sending anything,
kwikqa fixfound 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, or set
KWIKQA_ENDPOINTto use another endpoint. - KWIKQA_ENDPOINT=… needs … in the environment
- Export the credentials or model that endpoint needs, as Bring your own key lists them.
- With KWIKQA_ENDPOINT=…, a model is the endpoint's own model ID
- Set
KWIKQA_DIAGNOSIS_MODELto the model ID or deployment your endpoint serves, not an OpenRouter route. - 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.