# Troubleshooting Guide

## Common Issues

### Database Connection Failed

**Symptoms**: Service can't connect to database

**Solutions**:
1. Check if PostgreSQL is running: `docker ps`
2. Verify DATABASE_URL in .env
3. Check network connectivity: `docker network ls`
4. Review logs: `docker logs postgres-auth-local`

### Port Already in Use

**Symptoms**: Service fails to start with port error

**Solutions**:
1. Find process using port: `lsof -i :5001`
2. Kill process or change PORT in .env
3. Check docker-compose for port conflicts

### Prisma Client Not Generated

**Symptoms**: Import errors for Prisma Client

**Solutions**:
```bash
cd services/iam-service
pnpm prisma generate
```

### Build Failures

**Symptoms**: TypeScript or build errors

**Solutions**:
1. Clean build artifacts: `./scripts/utils/cleanup.sh`
2. Reinstall dependencies: `pnpm install`
3. Check TypeScript errors: `pnpm typecheck`

### Traefik Not Routing

**Symptoms**: 404 errors from Traefik

**Solutions**:
1. Check Traefik dashboard: http://localhost:8080
2. Verify service labels in docker-compose
3. Check routes.yml configuration
4. Review Traefik logs: `docker logs traefik-local`

## Getting Help

1. Check service logs: `./scripts/dev/logs.sh <service>`
2. Review GitHub Issues
3. Contact team lead
