Troubleshooting

This guide covers common issues you might encounter when running AspNetRun Microservices and how to resolve them.

Docker Issues

Docker Desktop Not Running

Problem: Error message “Cannot connect to the Docker daemon” Solution:

Start Docker Desktop
Wait for Docker to fully initialize (check system tray icon)
Verify Docker is running:
```
docker ps
```

Insufficient Resources

Problem: Services crash or fail to start with out-of-memory errors Solution:

Open Docker Desktop Settings
Go to Resources
Increase Memory to at least 4 GB
Increase CPU to at least 2 cores
Click “Apply & Restart”

Port Conflicts

Problem: “Port is already allocated” error when starting services Solution: Check which ports are in use:

# Windows
netstat -ano | findstr ":<PORT>"

# Linux/Mac
lsof -i :<PORT>

Common port conflicts:

Port	Service	Alternative Solution
5432	PostgreSQL (Catalog)	Stop local PostgreSQL or modify docker-compose.override.yml
5433	PostgreSQL (Basket)	Change port mapping in docker-compose.override.yml
1433	SQL Server	Stop local SQL Server
6379	Redis	Stop local Redis instance
5672/15672	RabbitMQ	Stop local RabbitMQ

To change a port mapping, edit docker-compose.override.yml:

catalogdb:
  ports:
    - "5434:5432"  # Changed from 5432:5432

Stale Containers or Images

Problem: Services show old code or fail to start after code changes Solution:

Stop and remove all containers:
```
docker-compose down
```
Remove old images:
```
docker-compose down --rmi all
```
Rebuild and start:
```
docker-compose up -d --build
```

For a complete clean start (removes volumes/data):

docker-compose down -v
docker system prune -a
docker-compose up -d --build

Using -v flag will delete all database data. Only use this if you want to start fresh.

Database Issues

Connection Timeouts

Problem: “Timeout expired” or “Connection refused” errors Solution:

Verify database containers are running:
```
docker-compose ps
```

Check database logs:

# PostgreSQL Catalog
docker-compose logs catalogdb

# PostgreSQL Basket
docker-compose logs basketdb

# SQL Server Order
docker-compose logs orderdb

Wait longer - databases need time to initialize (especially SQL Server)
Restart the specific database container:
```
docker-compose restart catalogdb
```

Migration Failures

Problem: Ordering service fails with migration errors Solution:

Check Ordering API logs:
```
docker-compose logs ordering.api
```
Verify SQL Server is fully started:
```
docker-compose logs orderdb
```
Look for “SQL Server is now ready for client connections”
Restart the Ordering API:
```
docker-compose restart ordering.api
```

If migrations are corrupted, recreate the database:

docker-compose down
docker volume rm src_postgres_catalog src_postgres_basket
docker-compose up -d

PostgreSQL Initialization Issues

Problem: Catalog or Basket service cannot connect to PostgreSQL Solution:

Check if database is ready:

docker exec -it catalogdb pg_isready -U postgres

Manually verify connection:

docker exec -it catalogdb psql -U postgres -d CatalogDb

If database is empty, check initialization:

docker-compose logs catalogdb | grep -i error

Service Communication Issues

gRPC Communication Failures

Problem: Basket service cannot connect to Discount gRPC service Symptoms:

“gRPC call failed” errors in Basket API logs
Products show incorrect prices

Solution:

Verify Discount service is running:
```
docker-compose ps discount.grpc
```
Check Discount service logs:
```
docker-compose logs discount.grpc
```
Verify the gRPC URL in Basket configuration:
```
docker exec -it basket.api env | grep GrpcSettings
```
Should show: GrpcSettings__DiscountUrl=https://discount.grpc:8081
Check certificate validation (common in development):
- The Basket service uses DangerousAcceptAnyServerCertificateValidator
- If this is disabled, you may need to add proper certificates

Restart both services:

docker-compose restart discount.grpc basket.api

RabbitMQ Connection Issues

Problem: Basket checkout doesn’t create orders, or “RabbitMQ connection failed” errors Solution:

Verify RabbitMQ is running:
```
docker-compose ps messagebroker
```
Check RabbitMQ logs:
```
docker-compose logs messagebroker
```
Access RabbitMQ Management UI:
- URL: http://localhost:15672
- Username: guest
- Password: guest
- Check for the BasketCheckout queue

Verify MassTransit configuration:

# Check Basket API
docker-compose logs basket.api | grep -i rabbitmq

# Check Ordering API
docker-compose logs ordering.api | grep -i rabbitmq

Verify connection strings:
```
docker exec -it basket.api env | grep MessageBroker
```
Should show:
- MessageBroker__Host=amqp://ecommerce-mq:5672
- MessageBroker__UserName=guest
- MessageBroker__Password=guest

Restart messaging-related services:

docker-compose restart messagebroker basket.api ordering.api

API Gateway Issues

Problem: Requests through API Gateway fail or return 404 Solution:

Verify all backend services are running:

docker-compose ps catalog.api basket.api ordering.api

Check Gateway logs:
```
docker-compose logs yarpapigateway
```

Test backend services directly:

curl http://localhost:6000/products
curl http://localhost:6001/basket/testuser
curl http://localhost:6003/orders

Test through Gateway:

curl http://localhost:6004/catalog-service/products
curl http://localhost:6004/basket-service/basket/testuser
curl http://localhost:6004/ordering-service/orders

Verify YARP configuration is loaded:

docker exec -it yarpapigateway cat /app/appsettings.json

Check for rate limiting (Ordering service has fixed window limiter):
- If you get 429 errors, wait a moment and retry
- Rate limit configuration is in appsettings.json

Application Issues

Web UI Not Loading

Problem: https://localhost:6065 doesn’t load or shows errors Solution:

Check Shopping Web logs:
```
docker-compose logs shopping.web
```

Verify API Gateway is accessible:

curl http://localhost:6004/catalog-service/products

Check Web configuration:
```
docker exec -it shopping.web env | grep ApiSettings
```
Should show: ApiSettings__GatewayAddress=http://yarpapigateway:8080
Check browser console for JavaScript errors
Try accessing via HTTP instead: http://localhost:6005

SSL/Certificate Errors

Problem: “SSL connection could not be established” or certificate warnings Solution: For development, the services use self-signed certificates:

Accept the browser certificate warning (click “Advanced” → “Proceed”)
Or use HTTP endpoints instead of HTTPS:
- Shopping Web: http://localhost:6005
- Catalog API: http://localhost:6000
- Basket API: http://localhost:6001

Empty Catalog

Problem: No products display in the Web UI Solution:

Check if Catalog database has seed data:

docker exec -it catalogdb psql -U postgres -d CatalogDb -c "SELECT * FROM catalog.products;"

Verify Catalog API is running in Development mode:
```
docker exec -it catalog.api env | grep ASPNETCORE_ENVIRONMENT
```
Should show: ASPNETCORE_ENVIRONMENT=Development

Check Catalog API logs for initialization:

docker-compose logs catalog.api | grep -i initial

If no seed data, restart Catalog service:
```
docker-compose restart catalog.api
```

Performance Issues

Slow Response Times

Problem: API responses are very slow Solution:

Check Docker resource allocation (increase if possible)
Verify Redis is working (Basket uses caching):
```
docker exec -it distributedcache redis-cli ping
```
Should return: PONG

Check for connection pool issues in logs:

docker-compose logs | grep -i "pool\|timeout"

Monitor container resource usage:
```
docker stats
```

Memory Leaks

Problem: Containers consume increasing memory over time Solution:

Monitor memory usage:
```
docker stats --no-stream
```
Restart problematic container:
```
docker-compose restart <service-name>
```
Check for logging issues (excessive logging can consume memory):
```
docker-compose logs --tail=100 <service-name>
```

Health Check Issues

Health Endpoints Failing

Problem: /health endpoints return unhealthy status Solution:

Check health endpoint for each service:

curl http://localhost:6000/health  # Catalog
curl http://localhost:6001/health  # Basket
curl http://localhost:6003/health  # Ordering

Health checks verify:
- Catalog: PostgreSQL connection to CatalogDb
- Basket: PostgreSQL connection to BasketDb + Redis connection
- Ordering: SQL Server connection to OrderDb

Check specific dependency:

# For Catalog/Basket - check PostgreSQL
docker exec -it catalogdb pg_isready

# For Basket - check Redis
docker exec -it distributedcache redis-cli ping

# For Ordering - check SQL Server
docker exec -it orderdb /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P SwN12345678 -Q "SELECT 1"

Review health check implementation in Program.cs of each service

Debugging Tips

View All Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f catalog.api

# Multiple services
docker-compose logs -f basket.api ordering.api

# Last 100 lines
docker-compose logs --tail=100

# Since specific time
docker-compose logs --since 2024-01-01T00:00:00

Execute Commands in Containers

# Interactive shell
docker exec -it catalog.api /bin/bash

# Run single command
docker exec catalog.api env

Inspect Container Configuration

# View environment variables
docker exec catalog.api env

# View mounted volumes
docker inspect catalog.api | grep -A 10 Mounts

# View network settings
docker inspect catalog.api | grep -A 10 Networks

Check Network Connectivity

# Test connection between containers
docker exec basket.api ping catalogdb
docker exec basket.api curl http://catalog.api:8080/health

Getting Help

If you’re still experiencing issues:

Check the GitHub Issues
Review service logs thoroughly:
```
docker-compose logs > all-logs.txt
```
Include the following information when reporting issues:
- Operating system and version
- Docker Desktop version
- Output of docker-compose ps
- Relevant log excerpts
- Steps to reproduce the issue

Next Steps

Running Locally - Setup guide
Monitoring - Health checks and monitoring
Architecture Overview - Understand the system design

Docker

Configuration

Operations

Docker Issues

Docker Desktop Not Running

Insufficient Resources

Port Conflicts

Stale Containers or Images

Database Issues

Connection Timeouts

Migration Failures

PostgreSQL Initialization Issues

Service Communication Issues

gRPC Communication Failures

RabbitMQ Connection Issues

API Gateway Issues

Application Issues

Web UI Not Loading

SSL/Certificate Errors

Empty Catalog

Performance Issues

Slow Response Times

Memory Leaks

Health Check Issues

Health Endpoints Failing

Debugging Tips

View All Logs

Execute Commands in Containers

Inspect Container Configuration

Check Network Connectivity

Getting Help

Next Steps

Build docs developers (and LLMs) love

Docker

Configuration

Operations

​Docker Issues

​Docker Desktop Not Running

​Insufficient Resources

​Port Conflicts

​Stale Containers or Images

​Database Issues

​Connection Timeouts

​Migration Failures

​PostgreSQL Initialization Issues

​Service Communication Issues

​gRPC Communication Failures

​RabbitMQ Connection Issues

​API Gateway Issues

​Application Issues

​Web UI Not Loading

​SSL/Certificate Errors

​Empty Catalog

​Performance Issues

​Slow Response Times

​Memory Leaks

​Health Check Issues

​Health Endpoints Failing

​Debugging Tips

​View All Logs

​Execute Commands in Containers

​Inspect Container Configuration

​Check Network Connectivity

​Getting Help

​Next Steps

Build docs developers (and LLMs) love

Docker Issues

Docker Desktop Not Running

Insufficient Resources

Port Conflicts

Stale Containers or Images

Database Issues

Connection Timeouts

Migration Failures

PostgreSQL Initialization Issues

Service Communication Issues

gRPC Communication Failures

RabbitMQ Connection Issues

API Gateway Issues

Application Issues

Web UI Not Loading

SSL/Certificate Errors

Empty Catalog

Performance Issues

Slow Response Times

Memory Leaks

Health Check Issues

Health Endpoints Failing

Debugging Tips

View All Logs

Execute Commands in Containers

Inspect Container Configuration

Check Network Connectivity

Getting Help

Next Steps