Troubleshooting Guide

Common issues and solutions for Bellamy Book installation and operation.

Quick Diagnosis

Check Service Status

# Docker services (run from dockerLocalENV)
docker compose ps

# System services (Linux)
sudo systemctl status postgresql
sudo systemctl status mongod
sudo systemctl status redis

# Check ports
netstat -tulpn | grep -E ':(3000|5000|5432|27017|6379)'

View Logs

# Docker logs (from dockerLocalENV or project root)
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres
docker compose logs -f mongodb

# Application logs
tail -f /var/log/bellamy-book/app.log

Installation Issues

Port Already in Use

Symptoms:

Error: "Address already in use"
Service fails to start

Solutions:

Find process using port:

# macOS/Linux
lsof -i :5000  # Backend
lsof -i :3000  # Frontend
lsof -i :5432  # PostgreSQL

# Windows
netstat -ano | findstr :5000

Kill the process:

# macOS/Linux
kill -9 <PID>

# Windows
taskkill /PID <PID> /F

Change port in configuration:

Backend: Update appsettings.json → ASPNETCORE_URLS
Frontend: Update .env → VITE_API_URL
Docker: Update docker-compose.yml ports section

Database Connection Errors

Symptoms:

"Connection refused"
"Authentication failed"
"Database does not exist"

Solutions:

1. Verify database is running:

# PostgreSQL
pg_isready
sudo systemctl status postgresql

# MongoDB
mongosh --eval "db.adminCommand('ping')"
sudo systemctl status mongod

# Redis
redis-cli ping
sudo systemctl status redis

2. Check connection strings:

# Test PostgreSQL connection
psql -h localhost -U postgres -d FacebookDb

# Test MongoDB connection
mongosh "mongodb://localhost:27017/bellamybook"

# Test Redis connection
redis-cli -h localhost -p 6379 ping

3. Verify credentials:

Check appsettings.json for correct username/password
Verify database user has proper permissions
Check firewall settings

4. Create database if missing:

# PostgreSQL
createdb FacebookDb
createdb MigrationDb

# MongoDB (auto-created on first connection)
mongosh --eval "use bellamybook"

MongoDB Replica Set Issues

Symptoms:

"MongoNetworkError: getaddrinfo ENOTFOUND"
Replica set not initialized
Authentication errors

Solutions:

1. Check replica set status:

docker exec -it mongodb mongosh -u root -p example --authenticationDatabase admin
rs.status()

2. Reconfigure replica set:

cfg = rs.conf()
cfg.members[0].host = "mongodb:27017"
rs.reconfig(cfg, {force: true})

3. Add hostname mapping (for host access):

# Add to /etc/hosts
sudo sh -c 'echo "127.0.0.1 mongodb" >> /etc/hosts'

4. Recreate MongoDB keyfile:

cd dockerLocalENV
openssl rand -base64 756 > mongo-keyfile
chmod 400 mongo-keyfile
docker-compose restart mongodb

.NET SDK Not Found

Symptoms:

"dotnet: command not found"
Build errors

Solutions:

1. Install .NET SDK:

# macOS
brew install --cask dotnet-sdk

# Linux
wget https://dot.net/v1/dotnet-install.sh
chmod +x ./dotnet-install.sh
./dotnet-install.sh --channel 6.0

2. Add to PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:$HOME/.dotnet

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

3. Verify installation:

dotnet --version
dotnet --info

Node.js Version Issues

Symptoms:

"Unsupported engine" errors
Build failures
Package installation errors

Solutions:

1. Use nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 16
nvm install 16
nvm use 16
nvm alias default 16

2. Verify version:

node --version  # Should be v16.14 or higher
npm --version

3. Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Runtime Issues

Backend API Not Starting

Symptoms:

API returns 500 errors
Connection refused
Service crashes

Solutions:

1. Check logs:

# Docker
docker-compose logs backend

# Manual
cd Src/backend/API
dotnet run

2. Verify configuration:

Check appsettings.json syntax
Verify connection strings
Check JWT secret key is set

3. Check database migrations:

cd Src/backend
dotnet ef database update --project DatabaseApplication

4. Verify dependencies:

dotnet restore
dotnet build

Frontend Not Loading

Symptoms:

Blank page
404 errors
CORS errors

Solutions:

1. Check environment variables:

cd Src/frontend
cat .env.local

2. Verify API URL:

Check VITE_API_URL matches backend URL
Ensure backend is running
Test API endpoint: curl http://localhost:5000/api/health

3. Clear build cache:

rm -rf node_modules .vite dist
npm install
npm run dev

4. Check browser console:

Open browser DevTools (F12)
Check Console for errors
Check Network tab for failed requests

5. CORS issues:

Verify backend CORS settings in appsettings.json
Add frontend URL to AllowedOrigins
Restart backend after CORS changes

Database Migration Errors

Symptoms:

Migration fails
"Table already exists" errors
Schema mismatch

Solutions:

1. Check migration status:

cd Src/backend
dotnet ef migrations list --project DatabaseApplication

2. Reset database (⚠️ Deletes all data):

# Drop and recreate
dotnet ef database drop --project DatabaseApplication --force
dotnet ef database update --project DatabaseApplication

3. Create new migration:

dotnet ef migrations add MigrationName --project DatabaseApplication
dotnet ef database update --project DatabaseApplication

4. Manual migration:

# Check migration SQL
dotnet ef migrations script --project DatabaseApplication

# Apply manually if needed
psql -U postgres -d FacebookDb -f migration.sql

Authentication Issues

Symptoms:

"Invalid token" errors
Login fails
Token expiration issues

Solutions:

1. Verify JWT configuration:

{
  "JwtSettings": {
    "SecretKey": "your-secret-key-here",
    "ExpirationMinutes": 60
  }
}

2. Check token expiration:

Verify token hasn't expired
Check system clock is synchronized
Increase ExpirationMinutes if needed

3. Clear browser storage:

// In browser console
localStorage.clear()
sessionStorage.clear()

4. Regenerate secret key:

openssl rand -base64 32
# Update in appsettings.json

File Upload Issues

Symptoms:

Upload fails
"File too large" errors
Timeout errors

Solutions:

1. Check file size limits:

{
  "Kestrel": {
    "Limits": {
      "MaxRequestBodySize": 1073741824  // 1GB
    }
  }
}

2. Verify storage configuration:

Check Storage.Provider setting
Verify storage path exists and is writable
Check disk space: df -h

3. Check permissions:

# Local storage
sudo chown -R www-data:www-data /var/www/uploads
sudo chmod -R 755 /var/www/uploads

# S3 storage
- Verify AWS credentials
- Check bucket permissions
- Verify bucket exists

Docker Issues

Containers Not Starting

Symptoms:

Containers exit immediately
"Cannot connect to Docker daemon"

Solutions:

1. Check Docker status:

# Linux
sudo systemctl status docker

# macOS
# Check Docker Desktop is running

2. Restart Docker:

# Linux
sudo systemctl restart docker

# macOS
# Restart Docker Desktop

3. Check Docker Compose version:

docker-compose --version  # Should be 2.0+

4. Clean up Docker:

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

Volume Permission Issues

Symptoms:

"Permission denied" errors
Files not accessible

Solutions:

1. Fix volume permissions:

# Find volume location
docker volume inspect bellamy-book_uploads

# Fix permissions
sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/bellamy-book_uploads/_data

2. Use named volumes:

volumes:
  uploads:
    driver: local

Network Issues

Symptoms:

Containers can't communicate
Connection refused between services

Solutions:

1. Check Docker network:

docker network ls
docker network inspect bellamy-book_default

2. Use service names:

Use service names (e.g., postgres, mongodb) not localhost
Example: Host=postgres;Port=5432 not Host=localhost

3. Recreate network:

docker-compose down
docker network prune
docker-compose up -d

Performance Issues

Slow Database Queries

Solutions:

1. Enable connection pooling:

{
  "ConnectionStrings": {
    "PrimaryConnectionString": "...;Pooling=true;MinPoolSize=10;MaxPoolSize=100"
  }
}

2. Add database indexes:

-- Check slow queries
EXPLAIN ANALYZE SELECT * FROM Posts WHERE UserId = '...';

-- Add indexes
CREATE INDEX idx_posts_userid ON Posts(UserId);

3. Optimize queries:

Use pagination
Limit result sets
Use projections (select only needed fields)

High Memory Usage

Solutions:

1. Check memory usage:

# Docker
docker stats

# System
free -h  # Linux
vm_stat  # macOS

2. Limit container resources:

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

3. Optimize application:

Enable caching
Use pagination
Optimize database queries
Review logging levels

Common Error Messages

"Connection string not found"

Solution:

Check appsettings.json has ConnectionStrings section
Verify environment variables are set
Check configuration file is in correct location

"JWT secret key is required"

Solution:

Set JwtSettings.SecretKey in appsettings.json
Or set JWT_SECRET_KEY environment variable
Generate new key: openssl rand -base64 32

"Database migration failed"

Solution:

Check database connection
Verify user has migration permissions
Review migration SQL for errors
Check database version compatibility

"CORS policy blocked"

Solution:

Add frontend URL to CorsSettings.AllowedOrigins
Check protocol (http vs https)
Verify port numbers match
Restart backend after changes

Getting Help

If you're still experiencing issues:

Check logs for detailed error messages
Review documentation for your specific issue
Search existing issues on GitHub
Create a new issue with:
- Error message
- Steps to reproduce
- Logs
- Configuration (sanitized)
- Environment details

Diagnostic Commands

Run these commands to gather diagnostic information:

# System information
uname -a
docker --version
docker-compose --version
dotnet --version
node --version

# Service status
docker-compose ps
docker-compose logs --tail=100

# Database status
psql -U postgres -c "SELECT version();"
mongosh --eval "db.version()"
redis-cli ping

# Network connectivity
curl http://localhost:5000/api/health
curl http://localhost:3000

# Disk space
df -h

# Memory
free -h  # Linux
vm_stat  # macOS

Prevention Tips

Regular backups of databases and configuration
Monitor logs for early warning signs
Keep dependencies updated (security patches)
Test changes in development first
Document custom configurations
Use version control for configuration files
Set up monitoring and alerts
Review logs regularly for errors

For more help, see:

Quick Diagnosis​

Check Service Status​

View Logs​

Installation Issues​

Port Already in Use​

Database Connection Errors​

MongoDB Replica Set Issues​

.NET SDK Not Found​

Node.js Version Issues​

Runtime Issues​

Backend API Not Starting​

Frontend Not Loading​

Database Migration Errors​

Authentication Issues​

File Upload Issues​

Docker Issues​

Containers Not Starting​

Volume Permission Issues​

Network Issues​

Performance Issues​

Slow Database Queries​

High Memory Usage​

Common Error Messages​

"Connection string not found"​

"JWT secret key is required"​

"Database migration failed"​

"CORS policy blocked"​

Getting Help​

Diagnostic Commands​

Prevention Tips​

Quick Diagnosis

Check Service Status

View Logs

Installation Issues

Port Already in Use

Database Connection Errors

MongoDB Replica Set Issues

.NET SDK Not Found

Node.js Version Issues

Runtime Issues

Backend API Not Starting

Frontend Not Loading

Database Migration Errors

Authentication Issues

File Upload Issues

Docker Issues

Containers Not Starting

Volume Permission Issues

Network Issues

Performance Issues

Slow Database Queries

High Memory Usage

Common Error Messages

"Connection string not found"

"JWT secret key is required"

"Database migration failed"

"CORS policy blocked"

Getting Help

Diagnostic Commands

Prevention Tips