# Troubleshoot Critter setup and previews

Start with the issue shown in the viewer. For HTML, check the selected page and website root. For framework apps, check project setup and the log for the version that failed.

## The command is not found

Check that Node.js and npm are available, and install the correct package:

```bash
node --version
npm --version
npm install -g @idamadam/critter
critter --version
```

The executable is `critter`. If installation succeeds but your shell cannot find it, make sure your npm global executable directory is on `PATH` and reopen the terminal. Use your Node installation's guidance for permissions rather than making broad permission changes to your project or system.

## An HTML page or asset is missing

Run from inside the Git repository and pass the actual file path:

```bash
critter view prototypes/checkout.html
```

An explicit file uses the Git repository as the website root. A directory command, such as `critter view prototypes/`, uses that directory instead. Root-relative asset URLs start at that selected root.

Check that CSS, JavaScript, images, and sibling pages are under the intended root. Historical versions only include committed files. If the page or asset did not exist at a selected commit, choose a later version or another page.

Hidden files, symlinks, `node_modules`, and private-key files are excluded from static previews. HTML mode also does not compile TypeScript or JSX, resolve npm imports, or run a backend. Use [a supported framework app](/docs/supported-projects/) when those build steps are needed.

To check an HTML setup, pass the same file or directory to `critter doctor`, such as `critter doctor prototypes/checkout.html`. It confirms the website root without looking for a `package.json`, dependencies or a build.

## A framework app is not detected

From the app's directory, run:

```bash
critter doctor
```

For an app in a larger repository, select the same path you use with the viewer:

```bash
critter doctor --app apps/admin
critter view --app apps/admin
```

Replace `apps/admin` with the app's actual directory. The report checks Node.js, Git context, project detection, package-manager availability, and common static-export blockers.

The selected framework app must have `vite` or `next` in its package dependencies and scripts required to run and build it. When a directory contains a framework app, that framework takes precedence over HTML detection. Pass an HTML file explicitly if you intend to review raw HTML instead.

## The live app does not start

While the dev server starts, the viewer shows **Starting dev server** with a timer, and the live version reloads on its own once the server answers. If the server stops, the viewer shows its command, exit code and recent output, with a hint when dependencies look missing. Fix the cause, such as installing dependencies with the project's package manager, then select **Restart dev server**.

To see the dev server's output as it runs:

```bash
critter view --verbose
```

## An earlier framework version will not build

A first historical build can take a minute or two while dependencies install and the app builds. The viewer shows the build's steps and how long it has taken. If it fails, the pane names the first error line and opens the build output; select **Retry build** after fixing a temporary problem, such as a failed network request. For the full log, use the commit SHA shown in the viewer or in Git:

```bash
critter logs <sha>
```

For an explicitly selected app:

```bash
critter logs <sha> --app apps/admin
```

Look for the first install or build error. Common causes are unavailable dependencies, missing committed files, incompatible Node or package-manager versions, and routes that cannot be statically exported. The live dev server working does not mean an old commit's production build will succeed.

You can stream development and snapshot output while running:

```bash
critter view --verbose
```

## A framework snapshot needs configuration

Historical framework builds omit values from your current `.env.local`. If your build needs a particular value, export it in the shell and explicitly allow that variable:

```bash
export VITE_API_URL=http://localhost:3000
critter view --build-env VITE_API_URL
```

Use the variable and value your app needs, and repeat `--build-env` for additional variables. Stop the existing viewer before relaunching with changed build configuration, so the normal viewer-reuse behavior does not leave the earlier configuration running.

The live app keeps its normal development environment. HTML mode does not inject environment variables or use `--build-env`. See [environment and external data](/docs/supported-projects/#environment-and-external-data) for the limits of historical builds.

## The page cannot load its data

A historical preview does not restore backend services, authentication state, or remote data. Keep the app's demo services available, and confirm the selected route or page existed in that commit. Framework pages must work in a static build.

To switch a running framework viewer to a known route:

```bash
critter route /checkout
```

Add `--check` to confirm the route loads in the live app and the selected version; the command exits with an error when either returns an HTTP error status.

For HTML, run `critter view` with the other page's file path. If synchronized controls behave differently because the two layouts changed substantially, turn synchronization off and inspect each side separately.

## Highlights stay pending

Highlights compare two loaded versions. While either side is building or the live dev server is starting, the control reads **Highlights pending**; hover it to see what it is waiting for. If a side failed to build or cannot load, fix that side first (see the sections above) or choose another version for it. You can still compare the panes without highlights.

## The command returns an existing viewer

This is expected when Critter is already running for the same app or website root. Use the URL it prints. Different projects and apps can run concurrently on automatically selected local ports.

If you want a second viewer for that same app, run:

```bash
critter view --new-instance
```

Include the same app or HTML target argument if you used one originally. Keep the viewer process running while reviewing.

## Applying an alternative fails

`critter explore use <group>/<variant>` requires a clean working tree. Check `git status` and preserve or finish your existing work before retrying. The command applies changes without moving `HEAD`; inspect and commit the result when ready.

If an alternative conflicts with newer work, review the reported conflict and use your normal Git workflow to resolve it. The [variations guide](/guides/explore-design-variations/) explains the shared-base workflow.

## Find command details

```bash
critter --version
critter --help
critter view --help
critter skills get core
```

Use the installed CLI's help and matching skill for its available commands. Include the output of `critter --version` when you report a problem. If you share diagnostic output for assistance, review it first and remove credentials, personal data, and private application details.

---

Canonical page: https://critter.sh/docs/troubleshooting/