# Troubleshooting

> Find out why a run failed or a result needs another look.

Web page: https://supercov.com/docs/troubleshooting
All Supercov pages for agents: https://supercov.com/llms.txt · Full text: https://supercov.com/llms-full.txt

When a run fails or a number looks wrong, have your agent inspect the output
before changing tests. An installation problem, a missing service and a
coverage gap need different fixes.

## The test run fails

First ask the agent to run the same test command without Supercov. If it also
fails, check the project's dependencies, runtime, test data and services first.

If it fails only through Supercov, keep both outputs and the run ID. Ask the
agent to check the [runner support reference](https://supercov.com/docs/supported-suites.md) and the
troubleshooting instructions bundled with its version:

```sh
npx supercov docs troubleshooting
```

Don't have the agent skip or weaken a failing test just to complete a coverage run.

## Installation doesn't work

Check the runtime requirements in [Supported languages](https://supercov.com/docs/supported-languages.md).
Your agent should use the package for the selected language and the project's
normal environment. An unavailable package registry or missing build tool
isn't a test problem.

## A file is missing or coverage looks too high

Ask the agent which source files were included and whether the full suite ran.
Generated code, monorepo boundaries or unusual build output can affect source
discovery. The agent can check whether explicit source roots are needed.

Do not interpret a missing file as 100% coverage. Use the [CLI reference](https://supercov.com/docs/cli.md)
and [runner support](https://supercov.com/docs/supported-suites.md) to investigate the run's scope.

## Assertion coverage is missing or lower than expected

A test run alone doesn't assess assertions: run
`runs latest assertions assess`, which needs `TYPESAFE_API_KEY`, and read the
result with `runs latest assertions`.

If a statement is not asserted, open it with
`runs latest assertions <file>:<line>` to see each test's answer. A check that
does not depend on the value, such as `assert.ok(total)`, catches no change to
it. A runner that cannot tell tests apart gives Jev no test to ask about.
[Assertion coverage](https://supercov.com/docs/assertions.md) explains the score.

## A run takes too long

The first pass may include package installation and measurement setup. Compare
it with the normal suite in the same environment. Later runs may be faster,
depending on the language and what changed.

Give the agent a time budget. It can use focused tests while working, then run
the full suite before comparing results. See [Speed and storage](https://supercov.com/docs/performance.md)
if repeated runs are still unexpectedly slow or taking too much disk space.

## Report a problem

Include the Supercov version, language and runtime, exact test command, error
output and whether the command works without Supercov. A small reproduction
helps when you can share one.

Run archives can contain source excerpts and test details. Check them for
private data before attaching them to a [GitHub issue](https://github.com/supercorp-ai/supercov/issues).