Troubleshooting¶

This guide covers common issues you might encounter when using this package and how to resolve them.

Setup Issues¶

Prek Hook Installation Fails¶

Problem: prek install returns an error or hooks don't run on commit.

Solutions:

1. Ensure you're in the project root directory
2. Verify Python virtual environment is activated

3. Reinstall prek:

   uv sync --group dev
   uv run prek install
   

4. Check if .git directory exists (must be a git repository)

5. Try running manually: uv run prek run --all-files

Virtual Environment Issues¶

Problem: Packages can't be found or dependencies conflict.

Solutions:

1. Create a fresh virtual environment:

   rm -rf .venv
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. Install dependencies:

   uv sync
   

3. Verify installation:

   python -c "import gwmock_pop; print(gwmock_pop.__version__)"
   

Development Issues¶

"Unstaged Changes" After Running Hooks¶

Problem: Prek modified files but they're not staged.

Solutions:

1. This is expected - review changes:

   git diff
   

2. Stage the changes:

   git add .
   

3. Try committing again

4. Or use git add -A to stage all changes before commit

Dependency Conflicts¶

Problem: uv pip install fails with conflict messages.

Solutions:

1. Check Python version:

   python --version
   

2. Create fresh virtual environment:

   rm -rf .venv && uv venv
   source .venv/bin/activate
   

3. Install with verbose output to see conflict:

   uv sync -vv
   

4. Check pyproject.toml for overly restrictive version constraints

Newer Version of Tool Breaks Things¶

Problem: Prek hooks or tools updated and now fail.

Solutions:

1. Check what changed:

   uv run prek auto-update --dry-run
   

2. Update individual tool:

   uv run prek auto-update --repo https://github.com/tool-repo
   

3. Test changes:

   uv run prek run --all-files
   

4. Pin to known-good version in .pre-commit-config.yaml:

   rev: v1.0.0 # Specific version instead of latest
   

Getting Help¶

If you encounter issues not listed here:

1. Check existing issues: Search GitHub Issues for your problem
2. Review logs carefully: Error messages usually point to the root cause
3. Search documentation: Many issues are covered in specific tool docs
4. Try minimal reproduction: Isolate the problem to a single file/command
5. Ask for help: Open an issue with:
   • Your environment (Python version, OS)
   • Steps to reproduce
   • Full error message/logs
   • What you've already tried