# Troubleshooting

## A plugin binary exits 127

The global `shadcn-maestro` package is missing or is another version than the plugin's. The binary prints the command to fix it, such as `npm i -g shadcn-maestro@<version>`. Run it yourself; the agent stops and asks instead of installing.

## `dependency_missing` or `dependency_outdated`

`shadcn-maestro reviewer` blocks (exit 3) until `agent-browser` and `shadcn` are on PATH at the latest npm version:

```sh
npm i -g agent-browser@latest shadcn@latest
```

When npm cannot be reached, the check is skipped with `dependency_check_skipped` and mapping continues.

## `EEXIST: file already exists` on `agent-browser`

Another install, for example Homebrew, already owns the `agent-browser` binary. Remove the other install or the stale link and run the npm command again. Recent npm versions may skip the postinstall script of `agent-browser`; that is fine, the native binaries ship in the package.

## `shadcn-maestro review` exits 3

The host refused to start the reviewer session. The command prints what to run: run that command yourself. In Codex, missing [sandbox rules](/agent/codex#sandbox-rules) also exit 3, with the lines to add.

## The browser review was not done

`agent-browser` could not launch Chrome, or the app has no dev script or did not start. The report lists the browser check under "not done"; on its own this does not make the delivery incomplete. Install Chrome and run again to get the browser check.

## `identity_mismatch`

The `author.session` or `reviewer.session` in the JSON is not the session the host exposes (`CLAUDE_CODE_SESSION_ID` or `CODEX_SESSION_ID`). Declare the session of the execution that runs the command.

## `self_review`

The same session tried to review its own annotation. Reviews must come from a separate execution: use `shadcn-maestro review`.

## `stale_map`, `stale_source` or `stale_review`

The source or the map changed after the annotation was written. Run `shadcn-maestro reviewer` to refresh the map, re-read the source and resubmit the annotation; then request a new review.

## `manager_conflict`

There is evidence for more than one package manager, such as two lockfiles. Remove the stale lockfile or set `packageManager` in `package.json` to the manager in use.

## `multiple_apps`

`--cwd` contains more than one app. Pick one of `data.candidates` and run `shadcn-maestro reviewer --cwd <path>`.

## `astro_not_supported` or `stack_not_supported`

The app is an Astro project or uses a framework without an adapter. shadcn-maestro supports Next.js (App and Pages Router), React with `createRoot`, React Router (library and framework mode), TanStack Start and Laravel with Inertia. The agent never offers a migration.