> Canonical HTML: [https://docs.schematic.rs/help/troubleshooting/](https://docs.schematic.rs/help/troubleshooting/)

# Troubleshooting

Start with the message Pup prints. Operational errors include a suggested next action and return a nonzero exit status.

## `pup: command not found`

Open a new terminal after installation. If Pup is still unavailable, confirm that its installation directory is on `PATH`:

**Terminal**

```bash
export PATH="$HOME/.local/bin:$PATH"
pup --version
```

Add the export to your shell profile if it resolves the problem. Running the installer again is safe and replaces the existing Pup binary with the current release.

## The browser does not open during login

`pup login` prints the Schematic authorization URL after it fails to open the default browser. Copy that URL into a browser on the same computer.

Keep the Pup process running until authorization returns to its local callback. If the callback has expired, stop the command and run `pup login` again.

## Login succeeds for the wrong organization

Run `pup login` again. When Schematic lists the organizations available to your account, select the one that should own new repositories and checks.

## Pup cannot find a linked repository

Run the link command from a Git repository:

**Terminal**

```console
$ pup repo link .
```

Pup associates the local repository path with a Schematic repository. A separate clone or checkout in another directory must be linked separately.

If the directory is not part of a Git repository, initialize or clone one before linking it.

## A repository stays in `preparing`

Inspect the current commit and progress:

**Terminal**

```console
$ pup repo status
● text-tools · main@a81d7c2 · preparing 68%
```

Preparation continues after `pup repo link` exits. If `HEAD` moves, the displayed commit and percentage change to the new target. If the state becomes `error`, follow the reason and suggested step. Authentication failures require a new `pup login`.

## Pup does not discover a supertest

Check each of the following:

- The file exists in the commit displayed by the check.
- `.pupignore` does not exclude the file.
- An untracked file included in a temporary Pup commit is not excluded by `.gitignore`.
- The declaration uses the supported Rust attribute, Python decorator, or Ruby DSL.
- The declaration is at file scope and has a unique name within the file.
- Its syntax is valid for the selected language.

For Python, Pup recognizes `@schematic.supertest` after `import schematic`, and `@supertest` after either `from schematic import supertest` or `from schematic import *`.

Pass a named selector to remove ambiguity:

**Terminal**

```console
$ pup check 'supertests/normalize_spaces.rs::normalizing_twice_changes_nothing'
```

**Terminal**

```console
$ pup check 'supertests/normalize_spaces.py::normalizing_twice_changes_nothing'
```

**Terminal**

```console
$ pup check 'supertests/normalize_spaces.rb::normalizing_twice_changes_nothing'
```

## A changed file is missing from a check

Read the commit object ID in the check row. If there were no uncommitted changes, Pup checked the selected commit rather than later edits. Otherwise, confirm that Pup created a temporary Pup commit containing the change.

Use Git to inspect the exact source identity:

**Terminal**

```console
$ git show --stat 4e92c1a
```

Then inspect `.pupignore`, size exclusions, and external symbolic links. Pup never silently ignores uncommitted changes and checks `HEAD` instead.

## Restore source from a temporary Pup commit

Pup retains temporary Pup commits under hidden Git references. Use the object ID from the check output with ordinary Git commands:

**Terminal**

```console
$ git show 4e92c1a
$ git restore --source=4e92c1a -- path/to/file
$ git branch recovered-work 4e92c1a
```

Creating a branch makes the commit visible in ordinary branch history. The temporary Pup commit is not a complete backup of ignored or excluded files.

## A check returns immediately

This is expected. `pup check` prints one row per selected supertest and exits after Schematic accepts them. A row may first be `pending` while its commit finishes preparing.

Retrieve rows from the most recent command with:

**Terminal**

```console
$ pup check status
```

Pass `--wait` when starting the checks or run `pup check status --wait` afterward to remain attached. Interrupting either command does not cancel remote work. Use `pup check cancel` only when you want to stop it.

## Understand `0 problems` and `verified`

Routine rows show the final supertest result directly:

- `0 problems` means the standard check detected no Problem.
- `1 problem` or another count means Pup has actionable analysis to inspect.
- `failed` means Pup confirmed a counterexample.
- `verified` appears only after `--prove` establishes the claim for the checked commit.
- `inconclusive` means proof was requested but Pup established neither a proof nor a confirmed failure.

Use `pup check status <reference>` to inspect Problems and their evidence.

## A large commit is slow to prepare

Inspect the current attempt:

**Terminal**

```console
$ pup repo status
```

Pup transfers changed eligible content relative to a prepared parent where possible. You can continue working while preparation runs. New checks wait in `pending` and start automatically when the selected commit is ready.

## Get help

If the output does not explain the problem, contact [support@schematic.tech](mailto:support@schematic.tech). Include the Pup version, repository name, commit object ID, attempt reference when available, and the complete operational error. Do not send source code or credentials by email.