Schematic Schematic Pup docs
Schematic website
Help

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
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
$ 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
$ 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
$ pup check 'supertests/normalize_spaces.rs::normalizing_twice_changes_nothing'
Terminal
$ pup check 'supertests/normalize_spaces.py::normalizing_twice_changes_nothing'
Terminal
$ 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
$ 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
$ 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
$ 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
$ 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. 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.