Troubleshooting

Quick Diagnosis

Check Services

Verify PostgreSQL and Redis are running

Review Logs

Check fkapi/api.log and fkapi/logs/performance.log

Test Connections

Verify database and cache connections work

Check Environment

Ensure .env file has all required variables

Setup Issues

Database Connection Errors

Error: could not connect to server

Problem: django.db.utils.OperationalError: could not connect to serverSolutions:

Verify PostgreSQL is running:

# On Linux/Mac
sudo systemctl status postgresql

# On Windows
# Check Services panel

# Test with pg_isready
pg_isready

Check database credentials in .env:

DATABASE_URL=postgresql://user:password@localhost:5432/fkapi

Create database if missing:

createdb fkapi

Test connection:

psql -U user -d fkapi -h localhost

Database does not exist

Problem: Database not created during setupSolution:

# Create database
createdb fkapi

# Or using psql
psql -U postgres
CREATE DATABASE fkapi;
\q

# Run migrations
cd fkapi
python manage.py migrate

Redis Connection Errors

Error: connecting to Redis

Problem: ConnectionError: Error connecting to RedisSolutions:

Verify Redis is running:

# On Linux/Mac
redis-cli ping
# Should return: PONG

# On Windows
# Check Services panel or use WSL

Check Redis URL in .env:

REDIS_URL=redis://localhost:6379/1

Start Redis:

# On Linux/Mac
redis-server

# Using Docker
docker run -d -p 6379:6379 redis

Test connection:

redis-cli
127.0.0.1:6379> PING
PONG

Module Import Errors

ModuleNotFoundError

Problem: ModuleNotFoundError: No module named 'core'Solutions:

Ensure correct directory:

cd fkapi
pwd  # Should show .../fkapi

Activate virtual environment:

# Linux/Mac
source venv/bin/activate

# Windows
venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt
pip install -r requirements-dev.txt

Verify installation:

pip list | grep django

Runtime Issues

Rate Limit Exceeded

403 Forbidden with rate limit message

Problem: API returns 403 with rate limit errorSolutions:

Wait for rate limit to reset (default: 1 hour)
Increase rate limit in .env:

API_RATE_LIMIT_RATE=200/hour

Whitelist IP for testing (in .env):

RATE_LIMIT_WHITELIST=127.0.0.1,192.168.1.100

Check current rate limit status:

redis-cli
KEYS "ratelimit:*"
TTL "ratelimit:127.0.0.1"

Clear rate limit (development only):

redis-cli
DEL "ratelimit:127.0.0.1"

Slow API Responses

API responses are slow

Solutions:

Check Redis cache is working:

redis-cli ping
redis-cli KEYS "fkapi:*"

Check response time headers:

curl -I http://localhost:8000/api/kits/arsenal-2024-home
# Look for: X-Response-Time, X-Query-Count

Enable query logging (temporarily in settings.py):

LOGGING = {
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',
        },
    },
}

Review slow query logs:

tail -f fkapi/logs/performance.log

Warm cache:

python manage.py warm_cache

Cache Not Working

Cache doesn't seem to be working

Solutions:

Verify Redis connection (see Redis section above)
Check cache configuration in settings.py:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": os.getenv("REDIS_URL"),
    }
}

Clear cache manually:

redis-cli FLUSHDB

Check cache keys:

redis-cli KEYS "fkapi:*"

Test cache from Django shell:

python manage.py shell
>>> from django.core.cache import cache
>>> cache.set('test', 'value', 60)
>>> cache.get('test')
'value'

Database Migration Errors

InconsistentMigrationHistory

Problem: django.db.migrations.exceptions.InconsistentMigrationHistorySolutions:

Check migration history:

python manage.py showmigrations

Fake migration (use with caution):

python manage.py migrate --fake core 0001

Reset migrations (development only):

# Delete migration files (keep __init__.py)
# Recreate migrations
python manage.py makemigrations
python manage.py migrate

Migrations not applying

Solutions:

Create migrations:

python manage.py makemigrations

Apply migrations:

python manage.py migrate

Check for conflicts:

python manage.py makemigrations --check

Testing Issues

Tests Failing

Tests fail with import errors

Solutions:

Check pytest.ini configuration:

[pytest]
DJANGO_SETTINGS_MODULE = test_settings
pythonpath = fkapi

Run tests from project root:

pytest fkapi/core/tests/

Clear test database:

rm fkapi/test_db.sqlite3

Verify test settings:

cat fkapi/test_settings.py

Coverage Not Working

Coverage report shows 0% or missing files

Solutions:

Install coverage tools:

pip install pytest-cov coverage

Run with coverage:

pytest --cov=fkapi/core --cov-report=html

Check configuration in pyproject.toml:

[tool.coverage.run]
source = ["fkapi/core"]

Scraping Issues

Scraping Fails with Connection Errors

ConnectionError or timeout

Problem: requests.exceptions.ConnectionError or timeoutSolutions:

Check internet connection
Verify target website is accessible:

curl -I https://www.footballkitarchive.com

Check proxy settings in core/http.py
Increase timeout in .env:

HTTP_TIMEOUT=30

HTML Parsing Errors

AttributeError or KeyError during parsing

Solutions:

Check if website structure changed
Log raw HTML for debugging:

logger.debug(f"HTML content: {html[:1000]}")

Review HTML fixtures in tests
Add defensive checks in parsers:

name = soup.find('h1')
if name:
    kit_name = name.text.strip()

Duplicate Data Issues

Duplicate clubs or kits created

Solutions:

Check slug uniqueness constraints
Use get_or_create() instead of create():

club, created = Club.objects.get_or_create(
    slug=slug,
    defaults={'name': name}
)

Find duplicates:

python manage.py shell
>>> from django.db.models import Count
>>> from core.models import Club
>>> Club.objects.values('slug').annotate(count=Count('id')).filter(count__gt=1)

API Issues

500 Internal Server Error

API returns 500 error

Solutions:

Check Django logs:

tail -f fkapi/api.log

Enable DEBUG mode (temporarily in .env):

DJANGO_DEBUG=True

Check database connection
Verify environment variables:

cat .env | grep -v "#"

Test endpoint directly:

curl -v http://localhost:8000/api/health

API Documentation Not Loading

/api/docs returns 404 or error

Solutions:

Verify Django Ninja is installed:

pip list | grep django-ninja

Check URL configuration in fkapi/urls.py:

path('api/', api.urls),

Access correct URL:

http://localhost:8000/api/docs

Performance Issues

High Database Query Count

Too many queries per request

Solutions:

Use select_related() for foreign keys:

Kit.objects.select_related('team', 'season')

Use prefetch_related() for many-to-many:

Club.objects.prefetch_related('competitions')

Check query count in response headers:

curl -I http://localhost:8000/api/kits/
# Look for: X-Query-Count

Enable query logging (see Slow API Responses)

Memory Issues

High memory usage

Solutions:

Use pagination for large datasets
Process data in chunks:

for kit in Kit.objects.all().iterator(chunk_size=1000):
    process(kit)

Clear cache periodically:

redis-cli FLUSHDB

Monitor with django-debug-toolbar (development)

Getting More Help

Check Logs

Review fkapi/api.log and fkapi/logs/performance.log

Enable Debug

Set DJANGO_DEBUG=True for detailed error messages

Documentation

Review other docs in /docs directory

GitHub Issues

Search existing issues or create new one

Common Error Messages

`django.core.exceptions.ImproperlyConfigured`

Usually means missing or incorrect settings. Check:

Environment variables in .env
Database configuration
Redis configuration

`django.db.utils.IntegrityError`

Database constraint violation. Check:

Unique constraints
Foreign key relationships
Required fields

`ninja.errors.ValidationError`

API request validation failed. Check:

Required parameters
Parameter types
Request body format

`core.exceptions.ScrapingError`

Scraping operation failed. Check:

Network connectivity
Target website availability
HTML structure changes

Still having issues? Open an issue on GitHub with:

Error message and full stack trace
Steps to reproduce
Environment details (OS, Python version, etc.)
Relevant logs

Contributing

Reference

Troubleshooting

Quick Diagnosis

Setup Issues

Database Connection Errors

Redis Connection Errors

Module Import Errors

Runtime Issues

Rate Limit Exceeded

Slow API Responses

Cache Not Working

Database Migration Errors

Testing Issues

Tests Failing

Coverage Not Working

Scraping Issues

Scraping Fails with Connection Errors

HTML Parsing Errors

Duplicate Data Issues

API Issues

500 Internal Server Error

API Documentation Not Loading

Performance Issues

High Database Query Count

Memory Issues

Getting More Help

Check Logs

Enable Debug

Documentation

GitHub Issues

Common Error Messages

`django.core.exceptions.ImproperlyConfigured`

`django.db.utils.IntegrityError`

`ninja.errors.ValidationError`

`core.exceptions.ScrapingError`

​Quick Diagnosis

​Setup Issues

​Database Connection Errors

​Redis Connection Errors

​Module Import Errors

​Runtime Issues

​Rate Limit Exceeded

​Slow API Responses

​Cache Not Working

​Database Migration Errors

​Testing Issues

​Tests Failing

​Coverage Not Working

​Scraping Issues

​Scraping Fails with Connection Errors

​HTML Parsing Errors

​Duplicate Data Issues

​API Issues

​500 Internal Server Error

​API Documentation Not Loading

​Performance Issues

​High Database Query Count

​Memory Issues

​Getting More Help

Check Logs

Enable Debug

Documentation

GitHub Issues

​Common Error Messages

​django.core.exceptions.ImproperlyConfigured

​django.db.utils.IntegrityError

​ninja.errors.ValidationError

​core.exceptions.ScrapingError

Quick Diagnosis

Setup Issues

Database Connection Errors

Redis Connection Errors

Module Import Errors

Runtime Issues

Rate Limit Exceeded

Slow API Responses

Cache Not Working

Database Migration Errors

Testing Issues

Tests Failing

Coverage Not Working

Scraping Issues

Scraping Fails with Connection Errors

HTML Parsing Errors

Duplicate Data Issues

API Issues

500 Internal Server Error

API Documentation Not Loading

Performance Issues

High Database Query Count

Memory Issues

Getting More Help

Common Error Messages

`django.core.exceptions.ImproperlyConfigured`

`django.db.utils.IntegrityError`

`ninja.errors.ValidationError`

`core.exceptions.ScrapingError`