Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
301 lines (239 loc) · 5.93 KB

TROUBLESHOOTING.md

File metadata and controls

301 lines (239 loc) · 5.93 KB
Raw

Troubleshooting Guide

Common Issues

Installation Issues

Issue: pip: command not found

Solution: Use python -m pip

python -m pip install -e ".[dev]"

Issue: ModuleNotFoundError: No module named 'ai_project'

Solution: Install in editable mode

pip install -e .

Issue: Permission denied during installation

Solution: Use virtual environment

python3.12 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

File Loading Issues

Issue: FileNotFoundError: File not found

Solution: Check file path

from pathlib import Path

file_path = Path("data.csv")
if not file_path.exists():
    print(f"File not found: {file_path}")
else:
    df = loader.load_csv(file_path)

Issue: Failed to parse CSV

Solution: Check delimiter and encoding

# Specify delimiter
df = loader.load_csv("data.csv", delimiter=";")

# Specify encoding
df = loader.load_csv("data.csv", encoding="latin-1")

# Or let auto-detection handle it
df = loader.load_csv("data.csv")

Issue: UnicodeDecodeError

Solution: Specify correct encoding

# Try different encodings
for encoding in ["utf-8", "latin-1", "utf-16"]:
    try:
        df = loader.load_csv("data.csv", encoding=encoding)
        print(f"Success with {encoding}")
        break
    except UnicodeDecodeError:
        continue

Data Validation Issues

Issue: ValidationError: value must be non-negative

Solution: Check data values

# View problematic rows
print(df[df["value"] < 0])

# Fix data
df = df[df["value"] >= 0]

Issue: ValidationError: label cannot be empty

Solution: Handle empty strings

# Remove empty labels
df = df[df["label"].str.strip() != ""]

# Or fill with default
df["label"] = df["label"].fillna("unknown")

Test Failures

Issue: FAILED tests/unit/test_loader.py::test_loader_loads_csv_file

Solution: Run with verbose output

pytest tests/unit/test_loader.py::test_loader_loads_csv_file -vv -s

Issue: AssertionError: assert 5 == 10

Solution: Check test data

# View test file
cat tests/fixtures/test_data/sample.csv

# Check fixture
pytest --fixtures | grep sample_csv_file

Issue: Coverage below 80%

Solution: Add tests for uncovered code

# Generate coverage report
pytest --cov=src/ai_project --cov-report=html

# View report
open htmlcov/index.html

# Add tests for uncovered lines

Performance Issues

Issue: Slow file loading

Solution: Check file size and use caching

# Enable caching (default)
loader = DataLoader(cache_enabled=True)

# First load caches data
df1 = loader.load_csv("large_file.csv")  # Slow

# Second load uses cache
df2 = loader.load_csv("large_file.csv")  # Fast

Issue: Memory usage too high

Solution: Process in chunks

# Read in chunks
for chunk in pd.read_csv("large_file.csv", chunksize=10000):
    # Process chunk
    result = pipeline.execute_chunk(chunk)

CI/CD Issues

Issue: GitHub Actions workflow fails

Solution: Check logs

# View workflow logs
gh run view <run-id> --log

# Or check on GitHub UI
# Actions tab → Workflow run → Job logs

Issue: PYPI_API_TOKEN not found

Solution: Add repository secret

Settings → Secrets and variables → Actions
New repository secret
Name: PYPI_API_TOKEN
Value: <your-token>

Issue: Tests pass locally but fail in CI

Solution: Check Python version

# Test with specific Python version
python3.11 -m pytest
python3.12 -m pytest
python3.13 -m pytest

FAQ

Q: How do I debug a failing test?

A: Use pytest with debugging options

pytest tests/unit/test_loader.py -vv -s --pdb

Q: How do I check code coverage?

A: Generate coverage report

pytest --cov=src/ai_project --cov-report=html
open htmlcov/index.html

Q: How do I run only unit tests?

A: Use pytest markers

pytest -m unit

Q: How do I run only integration tests?

A: Use pytest markers

pytest -m integration

Q: How do I format my code?

A: Use Black

black src tests

Q: How do I check for linting errors?

A: Use Ruff

ruff check src tests

Q: How do I type check my code?

A: Use Pyright

pyright src

Q: How do I create a release?

A: Create a tag

git tag v1.0.0
git push origin v1.0.0

Debug Logging

Enable Debug Logging

from ai_project.logger import configure_logging

configure_logging("DEBUG")

# Now all operations are logged
loader = DataLoader()
df = loader.load_csv("data.csv")

View Logs

# Run with logging
python -c "
from ai_project.logger import configure_logging
configure_logging('DEBUG')
from ai_project.processors.loader import DataLoader
loader = DataLoader()
df = loader.load_csv('data.csv')
"

Getting Help

1. Check Documentation

2. Search Issues

3. Start Discussion

4. Report Bug

  • Create Issue
  • Include error message, code, and steps to reproduce

5. Contact Support

Performance Profiling

Profile Code

import cProfile
import pstats

profiler = cProfile.Profile()
profiler.enable()

# Your code
df = loader.load_csv("data.csv")

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(10)

Benchmark Tests

pip install pytest-benchmark
pytest --benchmark-only

Last Updated: January 15, 2026