holocron/plugins/kyberforge/docs/research/docs/pre-commit/troubleshooting.md

topic, source_keys

topic	source_keys
troubleshooting	context7-pre-commit-com pre-commit-com

Common issues

Hooks don't run on git commit

pre-commit install was never run in this clone. Run it. Git hooks are per-clone — they are not committed.

Hook modified files but commit was blocked

Expected behavior. The hook fixed files, so the staged version is now stale. Re-stage the modified files and commit again.

git add -u
git commit -m "same message"

SKIP not working

The value must be the exact id field from the hook definition. Comma-separated, no spaces.

SKIP=check-yaml,trailing-whitespace git commit -m "msg"  # correct
SKIP=check-yaml, trailing-whitespace git commit -m "msg"  # wrong — space after comma

Hook runs but matches wrong files (or no files)

files: uses re.search(), not a full-string match. \.py$ matches any path ending in .py. To match only repo root: ^[^/]+\.py$.

Use identify-cli <filename> to see exactly what type tags a file has, then verify your types: filter.

Hook environment is stale or broken

pre-commit clean          # wipe all environments
pre-commit install-hooks  # rebuild everything

Or clean just a specific repo:

pre-commit gc             # remove only unused environments

rev is a branch name — autoupdate broke it

Branch refs are mutable; pre-commit resolves them at install time and then they drift. Always use a tag or commit SHA. Fix:

pre-commit autoupdate     # finds the latest tag and rewrites rev in place

validate-config returns an error

Schema violation in the YAML. Common causes:

• Missing id under a hook block
• Missing rev under a non-local repo block
• repo: local hook missing required language or entry fields
• Indentation error (YAML parsed but pre-commit schema rejected it)

check-hooks-apply fails

A hook's files/types filter matches zero files in the repo. Either broaden the filter or remove the hook. This is a sign the hook is dead weight.

check-useless-excludes fails

An exclude pattern matches no files. Remove or fix it.

SSH cloning fails in CI

Export SSH_AUTH_SOCK in the CI environment, or use HTTPS URLs for hook repos.

HTTP proxy needed

export http_proxy=http://proxy.example.com:3128
export https_proxy=http://proxy.example.com:3128
export no_proxy=localhost,127.0.0.1

Hook too slow in CI

• Check require_serial: false (default) — hooks run in parallel by default
• Cache $PRE_COMMIT_HOME keyed on the hash of .pre-commit-config.yaml
• Use --from-ref/--to-ref instead of --all-files to only check changed files

language: system deprecated warning

Renamed to language: unsupported. Old name still works as an alias but triggers a deprecation warning on newer versions.

pre-commit install -f wiped my existing hooks

-f overwrites .git/hooks/pre-commit unconditionally. Without -f, pre-commit migrates the existing hook so both run. Only use -f deliberately.

pretty-format-json fails but doesn't fix

pretty-format-json only fixes in-place when args: [--autofix] is passed. Without it, the hook just fails. Add --autofix to have it modify the file (the commit will then be blocked until you re-stage).

Skill/agent-specific gotchas

• Always call pre-commit validate-config after writing or modifying config — do not assume valid YAML is valid pre-commit schema.
• pre-commit autoupdate modifies the config file in-place. If a skill calls it, re-read the file to get updated rev values for display/logging.
• Local hooks with language: unsupported_script require the entry script to be executable. If the skill creates the script, chmod +x it.
• The stages key in a hook override must match what was set in default_install_hook_types (or the -t flags passed to pre-commit install), otherwise the hook will never run.
• always_run: true combined with pass_filenames: false is the correct pattern for repo-wide validators (test suites, manifest checks) that do not operate on individual files.