Skip to content

🐛 Debugging Common Issues

This guide covers common issues you might encounter while working with the DexaMinds platform and how to resolve them.

🔍 General Debugging Approach

  1. Check the logs ```bash # View application logs docker-compose logs -f

# View backend logs tail -f backend/logs/debug.log ```

  1. Verify services are running bash docker ps

  2. Check service status ```bash # Backend curl http://localhost:8000/health

# Frontend curl -I http://localhost:3000 ```

🚨 Common Issues & Solutions

1. Database Connection Issues

Symptoms: - "Could not connect to database" errors - Timeout when accessing database

Solutions:

# Check if PostgreSQL is running
docker ps | grep postgres

# Check PostgreSQL logs
docker-compose logs postgres

# Try connecting manually
PGPASSWORD=postgres psql -h localhost -U postgres -d dexaminds

2. Frontend Not Connecting to Backend

Symptoms: - API requests failing with CORS errors - "Connection refused" errors

Solutions: 1. Verify backend is running 2. Check NEXT_PUBLIC_API_URL in frontend .env 3. Ensure CORS is properly configured in backend

3. Dependency Issues

Symptoms: - Module not found errors - Version conflicts

Solutions:

# Frontend
rm -rf node_modules package-lock.json
npm install

# Backend
rm -rf venv
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\activate
pip install -r requirements.txt

4. Docker Container Issues

Symptoms: - Containers won't start - Port conflicts

Solutions:

# Stop and remove all containers
docker-compose down

# Rebuild containers
docker-compose build --no-cache

# Check for port conflicts
lsof -i :<port>  # Mac/Linux
netstat -ano | findstr :<port>  # Windows

5. Database Migration Problems

Symptoms: - Migration conflicts - Database schema out of sync

Solutions:

# Show migrations
python manage.py showmigrations

# Reset migrations (DEV ONLY)
find . -path "*/migrations/*.py" -not -name "__init__.py" -delete
find . -path "*/migrations/*.pyc" -delete
python manage.py makemigrations
python manage.py migrate --fake-initial

🛠 Debugging Tools

Backend (Python/Django)

  1. pdb Debugger python import pdb; pdb.set_trace() # Add to your code

  2. Django Debug Toolbar python # settings.py INSTALLED_APPS += ['debug_toolbar'] MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware'] INTERNAL_IPS = ['127.0.0.1']

Frontend (React/Next.js)

  1. React Developer Tools
  2. Install Chrome/Firefox extension

  3. Inspect component hierarchy and props

  4. Browser DevTools

  5. Console for errors
  6. Network tab for API calls
  7. Application tab for storage

📝 Common Error Messages

"Module not found: Can't resolve 'module'"

# Delete node_modules and reinstall
rm -rf node_modules
npm install

"Port already in use"

# Find and kill the process
lsof -i :3000  # Replace with your port
kill -9 <PID>

"Database is locked"

# For SQLite
rm db.sqlite3
python manage.py migrate
python manage.py createsuperuser

🔍 Performance Issues

Slow Database Queries

# Add to settings.py to log slow queries
LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',
            'handlers': ['console'],
        }
    },
}

Frontend Performance

  1. Use React DevTools Profiler
  2. Check bundle size with source-map-explorer
  3. Lazy load components

🆘 Getting Help

When asking for help, please provide: 1. Error message 2. Steps to reproduce 3. Environment details 4. What you've tried

📚 Additional Resources

Last Updated: June 2025