Troubleshooting

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

Setup Issues

Pre-commit Hook Installation Fails

Problem: pre-commit 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 pre-commit:

   pip uninstall pre-commit
   pip install pre-commit
   pre-commit install
   pre-commit install --hook-type commit-msg
   

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

5. Try running manually: pre-commit run --all-files

commitlint Not Running

Problem: Commit messages aren't validated despite npm install being run.

Solutions:

1. Verify npm install was successful:

   npm list @commitlint/config-angular
   

2. Re-install commitlint dependencies:

   npm install --save-dev @commitlint/cli @commitlint/config-angular
   

3. Reinstall pre-commit hooks:

   pre-commit install --hook-type commit-msg
   

4. Test manually:

   echo "invalid message" | commitlint
   echo "feat: valid message" | commitlint
   

Virtual Environment Issues

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

Solutions:

1. Create a fresh virtual environment:

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

2. Upgrade pip:

   python -m pip install --upgrade pip
   

3. Install dependencies:

   pip install -e ".[dev,docs,test]"
   

4. Verify installation:

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

Python Version Mismatch

Problem: python -m venv .venv fails or tests don't run with wrong Python version.

Solutions:

1. Check your Python version:

   python --version
   

2. Ensure Python 3.10 or higher is installed

3. Use specific Python version when creating venv:

   python3.11 -m venv .venv
   

4. Or use uv for version management:

   uv venv --python 3.11
   source .venv/bin/activate
   

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