Debugging¶

Start by recording the versions and checking what prek discovered:

prek --version
git --version
prek list
prek run --dry-run

Then rerun the smallest failing command with verbose tracing:

prek run check-yaml -vvv

Replace check-yaml with the ID of the failing hook.

A hook does not run during Git operations¶

Confirm that the expected Git shim is installed:

prek install
git config --show-origin --get core.hooksPath

prek install defaults to the pre-commit shim. Other stages require either default_install_hook_types in the config or an explicit prek install --hook-type <stage>. A hook's stages setting controls whether it is eligible to run, but does not install the corresponding Git shim.

If another tool already owned the hook, check the install output for migration mode. prek may be running both its own hook and a preserved .legacy hook.

A hook is skipped or receives no files¶

prek run without a file-selection option checks the files staged in Git. Try the whole repository and inspect the selection without executing hooks:

prek run --all-files --dry-run

Check files, exclude, types, types_or, exclude_types, stages, and any PREK_SKIP or SKIP value. To see the type tags prek assigns to a path, run:

prek util identify path/to/file

In a workspace, use prek list to confirm the project and use a project-qualified selector when hook IDs are repeated.

A config or workspace change is not detected¶

New and changed config files must be staged for the default staged-file run. This keeps config discovery and hook execution on the same snapshot:

git add prek.toml
prek run

Use the repository's YAML config filename instead when applicable.

If you added a nested config or changed .prekignore, rebuild workspace discovery with:

prek run --refresh

Hook installation or downloads fail¶

Use -vvv to identify whether the failing step is Git authentication, TLS, toolchain download, or the language package manager. Then check:

• Private repository authentication
• Proxy and certificate variables in the Environment Variable Reference
• Language-specific prerequisites in Language Support
• The checksum and trust boundary in the Security Guide

If a Rust-native fast path behaves differently from the pinned hook, compare it with:

PREK_NO_FAST_PATH=1 prek run check-yaml --all-files

Cache problems¶

Inspect the cache before removing anything:

prek cache dir
prek cache size
prek cache gc

prek cache clean removes cached hook repositories, environments, and managed tools, so the next run must download and prepare them again. Use it only after a normal retry and garbage collection do not resolve a corrupted environment.

Logs and bug reports¶

prek writes trace logs to $PREK_HOME/prek.log. By default this is ~/.cache/prek/prek.log on macOS and Linux, and the prek directory under %LOCALAPPDATA% on Windows. Choose a separate file for one reproduction with:

prek --log-file prek-debug.log run check-yaml -vvv

When reporting a bug, include the smallest reproducer, command, complete error, prek version, operating system, and relevant log section. Remove credentials, private repository URLs, user paths, and sensitive hook output before sharing a log publicly.