Files

T

Your Name 20d6c2549d Renamed from Boilerplate to CleverClaude

2025-08-10 00:20:59 +00:00

15 KiB

Raw Blame History

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=cleverclaude

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

# 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/cleverclaude: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 cleverclaude:local .
kind load docker-image cleverclaude: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/cleverclaude
Tool Documentation:

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!

15 KiB Raw Blame History

Troubleshooting Guide

🚀 Quick Fixes

Development Container Won't Start

uv Command Not Found

Virtual Environment Issues

🛠️ Tool-Specific Issues

Ruff Issues

Ruff Not Found in VS Code

Ruff Configuration Conflicts

Import Sorting Issues

Pyright Issues

Type Checking Errors

Pyright Not Found

Behave/BDD Issues

Step Definition Not Found

Hypothesis Integration Issues

Feature File Syntax Errors

🐳 Docker Issues

Container Build Failures

Docker Build Context Too Large

Permission Denied in Container

uv Not Found in Container

Container Runtime Issues

Container Exits Immediately

Resource Constraints

☸️ Kubernetes/Helm Issues

Helm Chart Issues

Template Rendering Errors

Resource Creation Failures

Deployment Issues

Image Pull Errors

HPA Not Scaling

🔄 CI/CD Issues

Forgejo Actions Issues

Pipeline Fails on Dependency Installation

Tests Fail in CI but Pass Locally

Docker Build Fails in CI

📊 Performance Issues

Slow Package Installation

Slow Tests

Slow CI Pipeline

🔍 Debugging Tips

General Debugging

Enable Verbose Output

Check Configuration

IDE Integration Debugging

VS Code Python Extension Issues

IntelliSense Not Working

🆘 Getting Additional Help

Documentation Resources

Community Support

Professional Support

Debugging Checklist

15 KiB

Raw Blame History