cleverclaude-core/docs/troubleshooting.md

# Troubleshooting Guide

This comprehensive troubleshooting guide covers common issues you might encounter when using the modern Python starter project and their solutions.

## 🚀 Quick Fixes

### Development Container Won't Start

**Issue**: VS Code shows "Dev container failed to start"

**Solutions**:
```bash
# 1. Check Docker is running
docker --version
docker ps

# 2. Free up disk space (containers need ~2GB)
docker system prune -f

# 3. Rebuild container from scratch
# In VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container"

# 4. Check Docker resource limits
# Docker Desktop → Settings → Resources
# Ensure: Memory ≥ 4GB, CPU ≥ 2 cores
```

### uv Command Not Found

**Issue**: `bash: uv: command not found`

**Solutions**:
```bash
# 1. Install uv
pip install uv

# 2. Check PATH
echo $PATH
which uv

# 3. Install with --user if needed
pip install --user uv
export PATH="$HOME/.local/bin:$PATH"

# 4. Restart shell
source ~/.bashrc  # or ~/.zshrc
```

### Virtual Environment Issues

**Issue**: Dependencies not found or wrong Python version

**Solutions**:
```bash
# 1. Clean and recreate environment
rm -rf .venv
uv venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows

# 2. Reinstall dependencies
uv pip install -e .[dev]

# 3. Verify environment
which python
python --version
pip list
```

## 🛠️ Tool-Specific Issues

### Ruff Issues

#### Ruff Not Found in VS Code

**Issue**: VS Code shows "Ruff is not installed"

**Solutions**:
```bash
# 1. Install ruff extension
# Extensions → Search "ruff" → Install "Ruff" by Astral Software

# 2. Check Python interpreter
# Ctrl+Shift+P → "Python: Select Interpreter"
# Choose the .venv/bin/python

# 3. Reload VS Code window
# Ctrl+Shift+P → "Developer: Reload Window"

# 4. Check ruff is installed
ruff --version
```

#### Ruff Configuration Conflicts

**Issue**: `ruff: error: Conflicting rules enabled`

**Solutions**:
```toml
# In pyproject.toml
[tool.ruff.lint]
select = [
    "E", "W",  # pycodestyle
    "F",       # pyflakes
    "I",       # isort
    "B",       # flake8-bugbear
    "C4",      # flake8-comprehensions
    "UP",      # pyupgrade
    "RUF",     # Ruff-specific
]
ignore = [
    "E501",    # Line too long (handled by formatter)
    "B008",    # Do not perform function calls in argument defaults
]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]          # Ignore unused imports
"tests/*.py" = ["D", "ANN"]       # Ignore docs and annotations in tests
"features/*.py" = ["D"]           # Ignore docs in BDD steps
```

#### Import Sorting Issues

**Issue**: Ruff and isort produce different results

**Solutions**:
```bash
# 1. Use ruff for import sorting (don't mix with isort)
ruff check --select I --fix .

# 2. Configure ruff import sorting
[tool.ruff.lint.isort]
known-first-party = ["your_package"]
force-single-line = true
```

### Pyright Issues

#### Type Checking Errors

**Issue**: `pyright: Cannot find implementation or library stub`

**Solutions**:
```bash
# 1. Install type stubs
uv pip install types-requests types-urllib3 types-click

# 2. Check pyrightconfig.json
{
  "typeCheckingMode": "strict",
  "reportMissingTypeStubs": false,  # Disable if too noisy
  "reportMissingImports": true,
  "pythonVersion": "3.11"
}

# 3. Add type: ignore for specific lines
import some_untyped_library  # type: ignore

# 4. Create stub files for internal modules
# stubs/internal_module.pyi
def some_function() -> str: ...
```

#### Pyright Not Found

**Issue**: `pyright: command not found`

**Solutions**:
```bash
# 1. Install pyright
uv pip install pyright

# 2. Install Node.js version if needed
npm install -g pyright

# 3. Check installation
pyright --version
which pyright

# 4. Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"
```

### Behave/BDD Issues

#### Step Definition Not Found

**Issue**: `behave: No step definition found for "When I do something"`

**Solutions**:
```python
# 1. Check step definition syntax (exact match required)
from behave import when

@when('I do something')  # Must match exactly
def step_when_do_something(context):
    pass

# 2. Check file location
features/
├── steps/
│   └── common_steps.py    # All step definitions here
└── feature_name.feature

# 3. Import in __init__.py if needed
# features/steps/__init__.py
from .common_steps import *

# 4. Check behave.ini configuration
[behave]
paths = features
```

#### Hypothesis Integration Issues

**Issue**: Hypothesis tests not running or failing randomly

**Solutions**:
```python
# 1. Proper Hypothesis integration
from behave import when
from hypothesis import given, strategies as st

@when('I test with random data')
def step_test_random(context):
    @given(st.text(), st.integers())
    def test_property(text, number):
        # Your test logic here
        result = process_data(text, number)
        assert result is not None
    
    # Run the test
    test_property()

# 2. Set Hypothesis settings
from hypothesis import settings, Verbosity

@settings(max_examples=100, verbosity=Verbosity.verbose)
@given(st.text())
def test_something(data):
    pass

# 3. Handle flaky tests
@given(st.integers(min_value=1, max_value=100))
def test_with_constraints(number):
    # Use constraints to avoid edge cases
    pass
```

#### Feature File Syntax Errors

**Issue**: `behave: Parser failure in feature file`

**Solutions**:
```gherkin
# 1. Check indentation (use spaces, not tabs)
Feature: Correct indentation
  Scenario: Proper spacing
    Given I have proper indentation
    When I use consistent spacing
    Then the parser should work

# 2. Check scenario structure
Feature: Feature name
  Background:  # Optional
    Given some common setup
  
  Scenario: Scenario name
    Given some condition
    When some action
    Then some outcome

# 3. Check language syntax
# features/example.feature
# language: en  # If using non-English

# 4. Validate with dry run
behave --dry-run
```

## 🐳 Docker Issues

### Container Build Failures

#### Docker Build Context Too Large

**Issue**: `docker build` is slow or fails with context size error

**Solutions**:
```dockerfile
# 1. Optimize .dockerignore
# .dockerignore
**/__pycache__
**/*.pyc
.git/
.venv/
node_modules/
*.log
.pytest_cache/
.hypothesis/
reports/

# 2. Use multi-stage builds
FROM python:3.13-slim AS builder
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.13-slim AS runtime
COPY --from=builder /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
```

#### Permission Denied in Container

**Issue**: Permission errors when running as non-root

**Solutions**:
```dockerfile
# 1. Fix file permissions in Dockerfile
RUN useradd -m -u 1000 appuser
RUN chown -R appuser:appuser /app
USER appuser

# 2. Set correct permissions on host
chmod +x scripts/*.sh

# 3. Use COPY with correct ownership
COPY --chown=appuser:appuser . /app
```

#### uv Not Found in Container

**Issue**: `uv: command not found` in Docker build

**Solutions**:
```dockerfile
# 1. Install uv in Docker
FROM python:3.13-slim
RUN pip install uv>=0.8.0

# 2. Use official uv image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 3. Verify installation
RUN uv --version
```

### Container Runtime Issues

#### Container Exits Immediately

**Issue**: Container starts then immediately exits

**Solutions**:
```bash
# 1. Check container logs
docker logs <container-id>

# 2. Run interactively to debug
docker run -it your-image /bin/bash

# 3. Check entrypoint/cmd
docker run your-image --help

# 4. Override entrypoint for debugging
docker run --entrypoint="" -it your-image /bin/bash
```

#### Resource Constraints

**Issue**: Container killed due to memory/CPU limits

**Solutions**:
```bash
# 1. Check resource usage
docker stats

# 2. Increase Docker limits
# Docker Desktop → Settings → Resources
# Memory: 4GB+, CPU: 2+ cores

# 3. Set container limits explicitly
docker run --memory=512m --cpus=1.0 your-image

# 4. Optimize Python memory usage
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
```

## ☸️ Kubernetes/Helm Issues

### Helm Chart Issues

#### Template Rendering Errors

**Issue**: `helm template` fails with template errors

**Solutions**:
```bash
# 1. Validate template syntax
helm template test ./k8s --debug

# 2. Check values.yaml syntax
yamllint k8s/values.yaml

# 3. Test with different values
helm template test ./k8s --set replicaCount=1

# 4. Validate against schema
helm lint k8s/
```

#### Resource Creation Failures

**Issue**: Pods fail to start or services unreachable

**Solutions**:
```bash
# 1. Check pod status
kubectl get pods -l app.kubernetes.io/name=boilerplate

# 2. Check pod logs
kubectl logs -l app.kubernetes.io/name=boilerplate

# 3. Describe failing resources
kubectl describe pod <pod-name>

# 4. Check resource constraints
kubectl top pods
kubectl describe node
```

### Deployment Issues

#### Image Pull Errors

**Issue**: `ErrImagePull` or `ImagePullBackOff`

**Solutions**:
```bash
# 1. Check image exists
docker pull ghcr.io/cleverthis/boilerplate:latest

# 2. Check image pull secrets
kubectl get secrets
kubectl describe secret <image-pull-secret>

# 3. Use local image for testing
# Build locally and use kind/minikube
docker build -t boilerplate:local .
kind load docker-image boilerplate:local

# 4. Update image pull policy
# In values.yaml
image:
  pullPolicy: IfNotPresent  # or Never for local images
```

#### HPA Not Scaling

**Issue**: Horizontal Pod Autoscaler not working

**Solutions**:
```bash
# 1. Check HPA status
kubectl get hpa
kubectl describe hpa <hpa-name>

# 2. Verify metrics server
kubectl top pods
kubectl get deployment metrics-server -n kube-system

# 3. Check resource requests/limits
# In values.yaml
resources:
  requests:
    cpu: 100m      # Required for HPA
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

# 4. Check HPA configuration
kubectl get hpa <hpa-name> -o yaml
```

## 🔄 CI/CD Issues

### Forgejo Actions Issues

#### Pipeline Fails on Dependency Installation

**Issue**: `uv pip install` fails in CI

**Solutions**:
```yaml
# .forgejo/workflows/ci.yml
- name: Install uv
  run: |
    pip install -q uv>=0.8.0
    uv --version

- name: Install dependencies  
  run: |
    uv pip install --system -e .[dev]
    # Use --system flag in containers

- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.cache/uv
    key: uv-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
```

#### Tests Fail in CI but Pass Locally

**Issue**: Different behavior between local and CI environments

**Solutions**:
```yaml
# 1. Use same Python version
container:
  image: python:3.13-slim  # Match local version

# 2. Set environment variables
env:
  PYTHONPATH: /app/src
  PYTHONDONTWRITEBYTECODE: 1
  PYTHONUNBUFFERED: 1

# 3. Install system dependencies
- name: Install system deps
  run: |
    apt-get update
    apt-get install -y git  # If needed for tests

# 4. Run with verbose output for debugging
- name: Run tests with debug
  run: |
    behave -v --no-capture
```

#### Docker Build Fails in CI

**Issue**: Docker build works locally but fails in CI

**Solutions**:
```yaml
# 1. Use BuildKit
- name: Build Docker image
  run: |
    export DOCKER_BUILDKIT=1
    docker build -t test-image .

# 2. Check available space
- name: Free disk space
  run: |
    df -h
    docker system prune -f

# 3. Use multi-stage build cache
- name: Build with cache
  run: |
    docker build \
      --cache-from ghcr.io/org/repo:cache \
      --tag test-image .
```

## 📊 Performance Issues

### Slow Package Installation

**Issue**: `uv pip install` taking too long

**Solutions**:
```bash
# 1. Use binary wheels when possible
uv pip install --only-binary=all -e .[dev]

# 2. Clear cache if corrupted
rm -rf ~/.cache/uv
uv pip install -e .[dev]

# 3. Use faster index
uv pip install --index-url https://pypi.org/simple/ -e .[dev]

# 4. Install from lock file
uv pip sync --system  # If you have uv.lock
```

### Slow Tests

**Issue**: BDD tests running slowly

**Solutions**:
```bash
# 1. Run tests in parallel
behave --processes 4

# 2. Skip slow tests during development
behave -t ~@slow

# 3. Use test database/fixtures
# features/environment.py
def before_all(context):
    context.db = setup_test_db()  # Fast in-memory DB

# 4. Profile test execution
behave --junit --junit-directory reports/
# Analyze reports/TESTS-*.xml
```

### Slow CI Pipeline

**Issue**: CI taking too long (>60 seconds goal)

**Solutions**:
```yaml
# 1. Use dependency caching
- uses: actions/cache@v3
  with:
    path: ~/.cache/uv
    key: uv-${{ hashFiles('pyproject.toml') }}

# 2. Run jobs in parallel
jobs:
  lint:
    runs-on: docker
    # ... lint steps
  
  test:
    runs-on: docker  
    # ... test steps
  
  build:
    needs: [lint, test]  # Only after others pass
    # ... build steps

# 3. Use faster runners if available
runs-on: ubuntu-latest  # vs self-hosted

# 4. Optimize Docker builds
- name: Build with cache
  run: |
    export DOCKER_BUILDKIT=1
    docker build --cache-from=registry/cache .
```

## 🔍 Debugging Tips

### General Debugging

#### Enable Verbose Output

```bash
# 1. Verbose mode for tools  
ruff check --verbose .
pyright --verbose
behave --verbose

# 2. Debug nox sessions
nox -s behave --verbose

# 3. Show environment info
python -m pip debug --verbose
uv pip list --verbose
```

#### Check Configuration

```bash
# 1. Validate pyproject.toml
python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb')))"

# 2. Check tool configs
ruff config
pyright --help

# 3. Verify paths
python -c "import sys; print(sys.path)"
echo $PYTHONPATH
```

### IDE Integration Debugging

#### VS Code Python Extension Issues

**Solutions**:
```bash
# 1. Check Python interpreter
# Ctrl+Shift+P → "Python: Select Interpreter"
# Should point to .venv/bin/python

# 2. Reload window after changes
# Ctrl+Shift+P → "Developer: Reload Window"

# 3. Check extension logs
# View → Output → Select "Python" from dropdown

# 4. Clear extension cache
# Ctrl+Shift+P → "Python: Clear Cache and Reload Window"
```

#### IntelliSense Not Working

**Solutions**:
```json
// .vscode/settings.json
{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.analysis.typeCheckingMode": "strict"
}
```

## 🆘 Getting Additional Help

### Documentation Resources

- **Main Documentation**: https://cleverthis.github.io/boilerplate
- **Tool Documentation**:
  - [uv docs](https://github.com/astral-sh/uv)
  - [Ruff docs](https://docs.astral.sh/ruff/)
  - [Pyright docs](https://microsoft.github.io/pyright/)
  - [Behave docs](https://behave.readthedocs.io/)
  - [nox docs](https://nox.thea.io/)

### Community Support

- **GitHub Issues**: Report bugs and get help
- **Discussions**: Ask questions and share tips
- **Matrix Chat**: Real-time community support

### Professional Support

For enterprise support and consulting:
- **Migration Services**: Help migrating large codebases
- **Training**: Team training on modern Python practices
- **Custom Implementation**: Tailored solutions for your needs

### Debugging Checklist

When reporting issues, include:

- [ ] Python version (`python --version`)
- [ ] uv version (`uv --version`)
- [ ] Operating system and version
- [ ] Full error message and stack trace
- [ ] Steps to reproduce
- [ ] Expected vs actual behavior
- [ ] Relevant configuration files (pyproject.toml, etc.)

---

**Still having issues?** Don't hesitate to open an issue or ask for help in the community channels. The modern Python toolchain is powerful, and we're here to help you succeed!