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:

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:

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

critter doctor

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

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:

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:

critter logs <sha>

For an explicitly selected app:

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:

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:

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

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:

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 explains the shared-base workflow.

Find command details#

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.