# Troubleshooting — tested.dev docs

Start with `tested doctor`. Then match the symptom below.

## Run doctor first

```
tested doctor
tested doctor --json
```

Hard FAILs must be green before push. WARNs are okay to understand.

## tested: command not found

Install the CLI, or skip local install and use the Action. After install, `td` is the same CLI. See [Install](https://tested.dev/docs/install).

```
pnpm add -D @tested/cli
# one-off
npx @tested/cli
```

## tested doctor FAIL under Node 24

Need Node 24 or newer. Doctor exits 1 until you upgrade.

## No coverage file

`tested run` writes `coverage/coverage-final.json` even if tests fail. If the file is still missing, the runner is not emitting Istanbul/V8 JSON. Run the runner with coverage yourself, then `tested diff` and `tested check`.

## invalid_credentials on push

- Install [tested-dev-app](https://github.com/apps/tested-dev-app), then mint the token at `https://app.tested.dev/repos/{owner}/{name}/settings`. It must match the repo in the app
- Env is `TESTED_TOKEN` or `TESTED_TOKEN_FILE`. Value is 64 hex characters. Settings shows it once
- After rotate, update the `TESTED_TOKEN` secret the same day
- `TESTED_API_URL` must be `https://app.tested.dev` (not a random preview deploy unless it shares the same DB)
- Repo must exist in the app (open it once after GitHub App install)

## 0 repos after install

- Confirm [tested-dev-app](https://github.com/apps/tested-dev-app) is installed on the correct GitHub user/org
- Sign out/in once; open `/repos` again
- Install-before-login needs membership sync. Open the app after install

## Empty 30-day chart

Chart is **mainline only**. PR pushes do not fill it. Upload with `tested push --mainline` or Action `mainline: true` on default branch.

## Patch gate skipped

Empty patch (no new executable lines) skips patch threshold by design. Project threshold still runs.

## Share link 404 / expired

- Public shares TTL ~30d; private shorter
- Owner can revoke all shares from repo Settings

## Sticky / App checks missing

- Hobby or Team plan required for sticky comments and App-posted required checks
- [tested-dev-app](https://github.com/apps/tested-dev-app) must stay installed
- Free plan: share URL still works. You can still require the Action job in branch protection

## Fork PR push failed

The gate works on fork PRs. `push: true` fails without secrets. GitHub does not pass repository secrets to workflows from forks.

Still stuck? Open a share of what `tested doctor --json` prints (redact tokens). See the [CLI](https://tested.dev/docs/cli) docs.