# Troubleshooting

> Fix stopped, stalled and timed-out reviews, invalid settings, missing MCP registration, PATH and reviewer install problems.

Most problems show up as a review that stopped, or as an error the command printed. Find the symptom below.

## Exit codes and round results

The runner’s commands exit with `0` on success, `1` on an error (for example an invalid argument, or a round that ended with an error), and `5` when the reviewer CLI is not in `PATH`. See the [CLI reference](https://cross-review.tlelabs.com/docs/reference/cli/#exit-codes).

A round that ends badly is described by the round result, not by the exit code. Its `exit_code` field says why:

| `exit_code` | Meaning                                                    |
| ----------- | ---------------------------------------------------------- |
| 2           | The round reached its deadline (default 18000 s, 5 hours). |
| 3           | The reviewer’s turn failed.                                |
| 4           | The reviewer stalled: no new output for a long time.       |

## A review stopped

A review stops when a round ends without a verdict. The agent then shows the reason (`next_reason`) and stops the session. Common reasons:

| Reason                  | Meaning                                                                     | What to do                                                                                      |
| ----------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `recoverable_timeout`   | The round hit the deadline, and the reviewer had started and made progress. | Ask the agent to resume the review. It continues the same reviewer thread.                      |
| `stalled`               | The reviewer stopped writing output.                                        | Ask the agent to resume if the session has a reviewer thread. Otherwise start the review again. |
| `reviewer_process_exit` | The reviewer process ended unexpectedly.                                    | Check that `codex` runs in a terminal, then ask the agent to resume or start again.             |

A stopped review that can be resumed stays in the **In progress** list on the [dashboard](https://cross-review.tlelabs.com/docs/guides/dashboard/), marked “stopped, resumable”, for an hour; after that it is listed in History as stopped, and it can still be resumed. Resuming it is your decision: the agent does not start a replacement session on its own. Say “resume the review” or “stop the review” to the agent.

### Timeouts (`exit_code` 2)

The default deadline is 18000 seconds (5 hours). When the runner reports a timeout caused by the deadline, a recoverable flag, a reviewer thread, and progress that it saw, the round ends with `recoverable_timeout`. Any timed-out session that has a reviewer thread can still continue: ask the agent to resume it. Only a session whose reviewer never started needs a new review; see [Can I resume a stopped review](https://cross-review.tlelabs.com/docs/start/faq/#can-i-resume-a-stopped-review).

### Stalls (`exit_code` 4)

The runner watches the reviewer’s output. When the output does not change for 12 checks in a row, it reports a stall and keeps any partial review it has. The checks run about every 120 seconds, so a stall is reported after roughly 24 minutes without output. The reviewer may still be working in that time, so check the dashboard before you resume.

## Settings file is invalid

`begin` fails with `CONFIG_INVALID` and creates no session. The message names the file and the problem, for example an unknown key or a `model` with spaces in it.

Fix the file that the message names:

- `~/.cross-review/config.json` for global settings
- `<workspace>/.cross-review/config.json` for the workspace

The file must be valid JSON. Only the keys in the [settings](https://cross-review.tlelabs.com/docs/guides/settings/#keys) table are allowed. You can also delete the file, or save the value again from the dashboard’s Settings page, which replaces a broken file.

## MCP server is not registered

The review skills use the `cross-review` MCP server. When it is missing, they run the same steps through the runner’s CLI, so reviews still work. The installer prints `not registered (runner CLI fallback)` when registration failed. It skips registration when `npm ci` failed.

Check the registration in each client:

**Claude Code**

```sh
claude mcp get cross-review
```

**Codex**

```sh
codex mcp get cross-review
```

If it is missing, run the installer again:

```sh
npx @tlelabs/cross-review@latest
```

Re-running it is safe. The registration is replaced, not duplicated.

## The cross-review command is not found

The installer writes `~/.local/bin/cross-review` on macOS and Linux. If the shell says the command is not found, the folder is not on `PATH`. The installer prints a note when that happens. Add this line to your shell profile, then open a new terminal:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

On Windows the installer does not write the command. Use `npx @tlelabs/cross-review dashboard` instead.

## The reviewer CLI is not found (exit 5)

The default reviewer is Codex. The review fails with `REVIEWER_NOT_FOUND` when the `codex` command is not in `PATH`. Install it, then check that it runs:

```sh
npm install -g @openai/codex
codex --version
```

Codex must also be signed in. Follow the Codex CLI’s own sign-in steps, then start the review again. For what the reviewer can reach on the network, see the [FAQ](https://cross-review.tlelabs.com/docs/start/faq/).

## The dashboard page says to use the printed link

A page that says “Open the dashboard from the link printed in the terminal” was opened without the token. The token changes each time the dashboard starts. Stop the old dashboard if it is still running, start it again, and open the new link.

## The dashboard port is in use

With `--port`, the dashboard fails when that port is taken. Pick another port, or leave out `--port` to get a free one.

## A plan is missing from the Plans page

- The plan must be in `<workspace>/.cross-review/plans/`. Plans in other folders are not listed.
- A Markdown file in that folder without the `loop-plan/v1` schema is shown as a plain document, not as a plan.
- The dashboard only scans the folder you started it in and up to 3 levels below. Start it higher with `--root`.

## Plans in git does not keep the plans

A rule in the root `.gitignore` ignores `.cross-review/`. The dashboard and `loop-plan` show a warning. The fix is in [Plans](https://cross-review.tlelabs.com/docs/guides/plans/#a-root-gitignore-can-still-block-plans).

## Reviews do not open in the dashboard

With **Follow reviews** on, `begin` returns `dashboard_error` when it cannot start or reach the dashboard, or when the browser does not open. The review still runs. Start the dashboard by hand with `cross-review dashboard` and open the link it prints.

## The update check fails

The footer or Settings page says that npm could not be reached, or that it did not answer in time. The check needs network access to the npm registry. It runs again at the next start, or when you press **Check now**.

> **Tip:**
>
> When a problem is not on this page, run `cross-review version`. It prints the runner version, which is `15` in this release. Then check the review session on the [dashboard](https://cross-review.tlelabs.com/docs/guides/dashboard/), which shows the reviewer’s last activity.