> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/troubleshooting/test-execution-issues.md).

# Test Execution Issues

Solutions to test execution issues.

### My test run looks stuck

The most common cause is not a stuck run at all: it is a run waiting for you.

When Kerno pauses for plan approval or an answer, the run reports that it needs your input and makes no progress until you reply. Ask your agent for the pending question, and answer it.

If nothing is pending, ask your agent to read the run's state directly, or to cancel and start again.

### Kerno says there's nothing to validate

Validation runs the scenarios already on disk for an entry point. If none exist, the run stops immediately and tells you to generate first. Nothing is created implicitly.

Generate tests for that entry point before validating it.

If you asked "what did my changes affect?" and got nothing back, check whether your changes are still uncommitted. The `changed` scope compares your working tree against `HEAD`, so once everything is committed there is nothing in the diff. Target the entry point or file directly instead.

### Kerno says my entry point doesn't exist

When you name a route Kerno's analysis did not list, Kerno searches your code for its handler before refusing.

* If the handler serves a different path, Kerno names that path. Ask again with the path your app serves.
* If no handler is found, Kerno lists the closest routes it knows. Check the method and path against your app, then ask again.
* If Kerno found the route but not its HTTP method, name the method yourself:

```
Use Kerno to generate tests for POST /users.
```

### Tests are failing with 401s or 403s

Kerno works out how each entry point authenticates by reading your source. When it gets this wrong, every scenario fails at the door.

* Check whether your auth needs a credential Kerno cannot obtain by itself. If your app signs tokens with a secret from an environment variable, provide it so Kerno can construct a valid token.
* Tokens Kerno signs itself use HMAC algorithms. If your verifier requires `RS256` or another asymmetric algorithm, Kerno needs a real login route to call instead.
* Flows requiring a person to complete a hand-off with an external identity provider cannot be automated. Those scenarios report as blocked.

### My MCP server rejects Kerno with a 401 or 403

Kerno's readiness check counts a refused sign-in as a live server, so a missing or wrong credential shows up once a test runs, reported as an environment problem. When the setup check of a new test is refused, the run stops before any test and shows no results.

* Check `MCP_AUTH_HEADERS` in `.kerno/.env`. It is a JSON map of header names to values, such as `{"Authorization": "Bearer <token>"}`. If the value does not parse, Kerno connects without it. An expired token fails the same way as a wrong one.
* Kerno sends these headers only to the host and port of your app's configured URL.
* A 403 can also mean the MCP path is wrong, since some gateways answer an unknown route with 403. Check the path in your app's URL.

To see why the server refused Kerno, ask your agent:

```
Use Kerno to list the tools my running MCP server advertises.
```

Kerno explains the 401 or 403 and says whether your headers were sent.

### A scenario reports as blocked

Blocked means the scenario could not run, usually because a dependency it needs is not configured. Kerno blocks a scenario it has already run only on evidence from that run, such as the status code its setup step received, which points at the missing piece. A planned scenario Kerno dropped because your environment cannot support it also reports as blocked, with the reason. It is neither a pass nor a fail. See [Environment Setup Issues](https://kerno.gitbook.io/docs/troubleshooting/environment-setup-issues.md).

### A scenario reports as not implemented

Kerno could not produce a working scenario for that case. This is reported honestly rather than counted as a pass. Try running an update on the entry point with guidance describing what that scenario should do.

### Kerno flagged a "potential bug" that isn't one

Potential bugs attach to scenarios that pass: Kerno found the entry point doing something the plan did not expect and documented the real behaviour.

If it is known or intended, tell your agent to ignore it and give your reason. Kerno records the decision for that entry point, and later reports, validation runs included, stop showing it. The test file keeps its potential-bug note until you next update that entry point's tests, which then document the behaviour as expected. Note that there is currently no way to reverse this through Kerno.

### My entry point changed on purpose and now everything fails

That is working as intended. Run an update rather than regenerating:

> "Use Kerno to update the tests for POST /users. The response no longer includes the role field."

Update keeps every scenario that still applies and edits only what your change requires.

{% hint style="info" %}
If you encounter issues or have questions, [message us on Slack](https://join.slack.com/t/kerno-community/shared_invite/zt-3fzrjxgog-voatSyyKY78uDj6QaNW4OQ), and we'll gladly help.
{% endhint %}
