Pup Docs
Help

Troubleshooting

Start with the error message and follow any recovery instructions Pup provides.

Authentication fails

If PUP_ACCESS_TOKEN is set, Pup uses that key instead of your saved key, including during pup login. Update or unset the variable before trying a different key.

Sign in to platform.schematic.tech and generate an API key. Then run pup login and enter the key when prompted:

Bash
$ pup login
  ? Pup API key › [hidden]
  ✓ Logged in as you@example.com

Pup cannot find a linked repository

Run pup link . inside a Git repository with at least one commit. Each clone or Git worktree needs its own link.

If Pup reports that a previously linked workspace is unavailable, check that you’re using the intended account. If the problem persists, contact Schematic support to recover the existing link. Switching branches or commits keeps the same link and history.

Pup does not discover a supertest

Confirm that:

  • The selected path includes the file containing your supertest.
  • The selected source includes your supertest.
  • .pupignore does not exclude its file.
  • The declaration uses the marker for your language and has a unique name within the file.

If the supertest is new or edited, include your uncommitted changes when prompted, or use --dirty.

Declare the function at the top level. Import supertest from schematic before using @supertest (from schematic import * also works). Alternatively, use import schematic with @schematic.supertest.

Declare the function at the top level. Use #[supertest] with use schematic::supertest;, or use #[schematic::supertest].

Include schematic.h and put SUPERTEST before a top-level void function.

Use [Supertest] on a public static method, with using Schematic;.

Import supertest from schematic-supertest and assign the result of supertest to a named top-level constant.

Use @Supertest on a public static method, with import tech.schematic.Supertest;.

Place --% supertest immediately before a labeled process. The process label is the supertest name, and the enclosing entity’s input ports define its inputs.

See Declare a supertest for an example, and Select supertests for selecting a file, directory, or named supertest.

Pup reports too many supertests

One command can select up to 128 supertests. Pass a file, a smaller directory, or file::supertest_name to check fewer supertests.

A changed file is missing

Check that the change is included in the source you selected. --commit checks committed code only. To include working changes, accept the prompt from pup check or use --dirty.

Check .pupignore in the code you’re checking. Untracked files matched by .gitignore are also excluded. See Exclude files for file limits and unsupported symlinks or submodules.

An existing check is blocked or canceled

Inspect the reason with pup status --check <number>. After a blocked, errored, or canceled check stops, rerun your original pup check command to start another attempt. The earlier attempt remains in history. Pup waits if it is still stopping.

If submission is interrupted, rerun the same command with unchanged source to recover it. If a check stays blocked or cancellation doesn’t finish, contact Schematic support.

A result is missing details

Press Enter in the interactive view, or use pup status --check <number> --details, to see the full explanation and evidence. If details are still being prepared, use pup status --check <number> --watch to follow updates. See Result meanings for the result labels.

A result refers to older code

pup status shows existing checks. Editing your files does not update those results. Check the displayed commit and run pup check again, including your changes when prompted, to check the updated code.

A fix is unavailable or won’t apply

pup fix waits while a proposal is pending. Press Ctrl+C to stop waiting without canceling the check, or use pup status --check <number> --watch to follow updates. If no proposal is available, use pup status --check <number> --details to review the finding and work on a fix.

If a patch no longer applies, Pup leaves your files unchanged. Preview the proposal with --dry-run. Recheck the affected supertest against your current code, then review any proposal for the new check. Uncommitted changes alone don’t prevent applying a fix.

If your files, staging, or current commit change after the preview, run pup fix again to review the updated preview. If application is interrupted, inspect your files for changes already applied.

Get help

Contact Schematic support with the output of pup --version, the command you ran, and the full error message. Include the repository name, commit ID, and check number shown in Pup’s output when relevant. Do not send API keys or source code by email.