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

# 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](https://platform.schematic.tech) and generate an API key.
Then run `pup login` and enter the key when prompted:

**Bash**

```console
$ 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](mailto:support@schematic.tech)
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`.

**Python:** 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`.

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

**C:** Include `schematic.h` and put `SUPERTEST` before a top-level `void` function.

**C#:** Use `[Supertest]` on a public static method, with `using Schematic;`.

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

**Java:** Use `@Supertest` on a public static method, with `import tech.schematic.Supertest;`.

**VHDL:** 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](/pup/supertests/#declare-a-supertest) for an example, and
[Select supertests](/pup/commands/checks/#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](/pup/help/source/#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](mailto:support@schematic.tech).

## 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](/pup/commands/checks/#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`](/pup/commands/checks/#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`](/pup/commands/checks/#pup-status) 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](mailto:support@schematic.tech) 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.