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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# .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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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:

# 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:

// .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
  • Ruff docs
  • Pyright docs
  • Behave docs
  • nox docs

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!