Troubleshooting

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.

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, 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.

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 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

claude mcp get cross-review

Codex

codex mcp get cross-review

If it is missing, run the installer again:

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:

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:

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.

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.

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, which shows the reviewer’s last activity.