1778 Troubleshoot 60f413ef

Troubleshoot Workflow

Debug and fix pre-commit hook issues.

Trigger

• "fix pre-commit"
• "pre-commit failing"
• "hook not working"
• "debug pre-commit"
• "pre-commit error"

Common Issues and Solutions

1. Hooks Not Running

Symptoms:

• Git commits without running hooks
• No output when committing

Solutions:

# Reinstall hooks
pre-commit install

# Also install commit-msg hooks if needed
pre-commit install --hook-type commit-msg

# Verify hook is installed
ls -la .git/hooks/pre-commit

2. Hook Execution Errors

Symptoms:

• Hook fails with error messages
• Specific hook returns non-zero exit code

Debug Steps:

# Run with verbose output
PRE_COMMIT_VERBOSE=1 pre-commit run <hook-id> --all-files

# Run specific hook on specific file
pre-commit run <hook-id> --files path/to/file.py

# Check hook environment
pre-commit run <hook-id> --verbose

3. Cache/Environment Issues

Symptoms:

• "Failed to install..." errors
• Inconsistent behavior
• Wrong versions running

Solutions:

# Clear all cached environments
pre-commit clean

# Reinstall with fresh dependencies
pre-commit install --install-hooks

# Check cache location
ls ~/.cache/pre-commit/

4. Version Mismatch

Symptoms:

• "Hook not found" errors
• Repository version doesn't have expected hook

Solutions:

# Update hooks to latest versions
pre-commit autoupdate

# Check available hooks in repo
pre-commit try-repo <repo-url> --all-files

# Validate configuration
bun run Tools/HookValidator.ts

5. Configuration Errors

Symptoms:

• YAML parsing errors
• "Invalid config" messages

Solutions:

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('.pre-commit-config.yaml'))"

# Validate configuration
bun run Tools/HookValidator.ts --verbose

# Check for common issues
pre-commit validate-config .pre-commit-config.yaml

6. Slow Hook Execution

Symptoms:

• Hooks take too long
• Timeout errors

Solutions:

# Limit files processed
- id: slow-hook
  files: ^src/  # Only check src/ directory

# Run hooks in parallel (default)
# Or force serial for problematic hooks
- id: problematic-hook
  require_serial: true

# Skip slow hooks temporarily
SKIP=slow-hook git commit -m "message"

7. Dependency Issues

Symptoms:

• "ModuleNotFoundError"
• "Package not found"
• Missing dependencies

Solutions:

# Add required dependencies
- id: mypy
  additional_dependencies:
    - types-requests
    - pydantic>=2.0

# For node hooks
- id: eslint
  additional_dependencies:
    - eslint@9.14.0
    - typescript
    - "@typescript-eslint/parser"

8. Git Hook Conflicts

Symptoms:

• Other tools overwriting hooks
• Husky/lefthook conflicts

Solutions:

# Check what's in hooks directory
cat .git/hooks/pre-commit

# Reinstall pre-commit hooks
pre-commit install --allow-missing-config

# If using husky, disable it
rm -rf .husky

9. Terraform Hook Issues

Symptoms:

• terraform_validate fails
• "Provider not found"

Solutions:

# Initialize terraform first
terraform init

# Clear terraform cache
rm -rf .terraform
terraform init

# Use retry option
- id: terraform_validate
  args:
    - --hook-config=--retry-once-with-cleanup=true

10. File Pattern Issues

Symptoms:

• Hook not running on expected files
• Hook running on wrong files

Debug:

# Test file pattern matching
pre-commit run <hook-id> --files specific/file.py

# Check what files would be matched
pre-commit run <hook-id> --all-files --verbose

Fix:

# Use correct regex patterns
- id: eslint
  files: \.[jt]sx?$  # Matches .js, .jsx, .ts, .tsx
  exclude: ^(dist|node_modules)/

Debug Techniques

Enable Verbose Mode

PRE_COMMIT_VERBOSE=1 pre-commit run --all-files

Trace Mode (for pre-commit-terraform)

PCT_LOG=trace pre-commit run terraform_validate

Check Hook Exit Code

pre-commit run <hook-id> --all-files; echo "Exit code: $?"

Inspect Hook Environment

# Find hook's virtual environment
ls ~/.cache/pre-commit/

# Activate and inspect
source ~/.cache/pre-commit/<hash>/py_env-python3.11/bin/activate
pip list

Test Hook in Isolation

# Try running hook directly from repo
pre-commit try-repo https://github.com/psf/black --all-files

Recovery Steps

Complete Reset

# 1. Remove all hooks
pre-commit uninstall

# 2. Clear cache
pre-commit clean

# 3. Remove git hooks
rm .git/hooks/pre-commit
rm .git/hooks/commit-msg

# 4. Reinstall
pre-commit install --install-hooks
pre-commit install --hook-type commit-msg

# 5. Test
pre-commit run --all-files

Skip Hooks Temporarily

# Skip all hooks (use sparingly)
git commit --no-verify -m "emergency commit"

# Skip specific hooks
SKIP=flake8,mypy git commit -m "skip linting"

Error Messages Reference