Troubleshooting

Database Connection Issues

Symptom


sqlalchemy.exc.OperationalError: could not connect to server

Solution

Check PostgreSQL is running:


docker ps | grep postgres

Verify DATABASE_URL is correct:


echo $DATABASE_URL
# Should be: postgresql://user:pass@host:port/dbname

Test connection directly:


psql $DATABASE_URL -c "SELECT 1"

Check PostgreSQL logs:


docker logs <postgres-container-id>

AI Service Connection Issues

Symptom


HTTPException: AI service unavailable (502)

Solution

Verify AI service is running:


curl http://localhost:8001/health

Check AI_SERVICE_URL in .env:


echo $AI_SERVICE_URL
# Should match the actual service location

Check network connectivity:


# From API Gateway container
ping ai-service

Review AI service logs:


docker logs <ai-service-container-id>

Migration Issues

Symptom


alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'

Solution

Check current migration state:


uv run alembic current
uv run alembic history

Verify migration files exist:


ls alembic/versions/

Reset database (destroys all data):


uv run alembic downgrade base
uv run alembic upgrade head

Create new migration if schema changed:


uv run alembic revision --autogenerate -m "fix schema"

Azure Storage Issues

Symptom


HTTPException: Failed to upload image (500)

Solution

Verify Azure connection string:


# Test with Azure CLI
az storage container list --connection-string "$AZURE_STORAGE_CONNECTION_STRING"

Check container exists:


az storage container show \
  --name dermadetect-images \
  --connection-string "$AZURE_STORAGE_CONNECTION_STRING"

Verify connection string format:


# Should contain:
# - AccountName=...
# - AccountKey=...
# - DefaultEndpointsProtocol=https
echo $AZURE_STORAGE_CONNECTION_STRING

Check Azure Storage logs in portal

Image Upload Issues

Symptom


HTTPException: Incorrect file type (400)

Solution

Verify file type is supported:
- Allowed: image/jpeg, image/jpg, image/png
Check base64 encoding:


# Should start with:
data:image/jpeg;base64,/9j/4AAQSkZJRg...

Verify image size:
- Maximum: 2MB (default, configurable via MAX_UPLOAD_SIZE_MB)

Validation Errors

Symptom


422 Unprocessable Entity
{
  "detail": [
    {"loc": ["body", "userId"], "msg": "field required"}
  ]
}

Solution

Check request format matches schema:
- Use camelCase for field names
- Include all required fields
- Match enum values exactly
Review API documentation:


# Open Swagger UI
open http://localhost:8000/docs

Validate request payload:


from src.schemas.anamnesis import AnamnesisRequest
 
# Test validation
try:
    request = AnamnesisRequest(**payload)
except ValidationError as e:
    print(e.errors())

Performance Issues

Symptom

Slow response times (greater than 2 seconds)

Solution

Check database query performance:


# Enable SQL logging
export DB_ECHO=true

Monitor AI service latency:


# Add timing logs in ai_client.py
start = time.time()
response = await client.post(...)
logger.info(f"AI call took {time.time() - start}s")

Check connection pool:


# In database/session.py
engine = create_async_engine(
    settings.database_url,
    pool_size=10,  # Increase if needed
    max_overflow=20
)

Profile slow endpoints:


uv run pytest --profile

Test Failures

Symptom


FAILED src/api/ai_test.py::test_predict_diagnosis

Solution

Run tests with verbose output:


uv run pytest -vv

Check testcontainer logs:


uv run pytest --log-cli-level=DEBUG

Verify Docker is running:


docker ps

Clean test cache:


rm -rf .pytest_cache
uv run pytest --cache-clear

Getting Help

If issues persist:

Check service logs for error messages
Review recent code changes
Consult the Architecture documentation
Check GitHub issues for similar problems
Contact the development team