Troubleshooting Guide

This guide helps diagnose and resolve common issues with the AzharStore Medusa backend.

Table of Contents

• Docker Issues
• Database Issues
• Redis Issues
• Backend Issues
• Frontend Issues
• API Issues
• Migration Issues
• Performance Issues
• Security Issues

Docker Issues

Docker Compose Won't Start

Symptoms: - docker compose up fails - Services exit immediately - Port binding errors

Solutions:

1. Check Docker is running:

   docker --version
   docker ps
   

2. Check for port conflicts:

   netstat -tuln | grep -E '3000|5432|6379|9000'
   

3. Stop conflicting services or change ports in docker-compose.yml

4. Check Docker logs:

   docker compose logs
   

5. Rebuild containers:

   docker compose down
   docker compose build --no-cache
   docker compose up -d
   

Container Keeps Restarting

Symptoms: - Container status shows Restarting - Logs show startup errors

Solutions:

1. View container logs:

   docker compose logs -f <service-name>
   

2. Check environment variables:

   docker compose config
   

3. Enter container to debug:

   docker compose exec <service-name> bash
   

4. Check resource limits:

   docker stats
   

Volume Mount Issues

Symptoms: - Data not persisting - Permission errors - Volume not found

Solutions:

1. List volumes:

   docker volume ls
   

2. Inspect volume:

   docker volume inspect <volume-name>
   

3. Recreate volume:

   docker compose down -v
   docker compose up -d
   

Database Issues

Cannot Connect to PostgreSQL

Symptoms: - Connection refused errors - Timeout errors - Authentication errors

Solutions:

1. Check PostgreSQL is running:

   docker compose ps postgres
   

2. Check DATABASE_URL in .env:

   grep DATABASE_URL .env
   

3. Test connection:

   docker compose exec postgres pg_isready -U postgres
   

4. Check PostgreSQL logs:

   docker compose logs postgres
   

5. Verify credentials:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT 1;"
   

Migration Failures

Symptoms: - Migration script fails - Tables not created - Schema mismatch

Solutions:

1. Check migration status:

   docker compose exec medusa npx medusa db:migrate --show
   

2. Revert migrations:

   docker compose exec medusa npx medusa db:revert
   

3. Re-run migrations:

   docker compose exec medusa npx medusa db:migrate
   

4. Check for locked migrations:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM medusa_migrations;"
   

5. Manually unlock:

   docker compose exec postgres psql -U postgres -d medusa -c "DELETE FROM medusa_migrations WHERE name = 'locked-migration';"
   

Database Performance Issues

Symptoms: - Slow queries - High CPU usage - Connection timeouts

Solutions:

1. Check active queries:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"
   

2. Kill long-running queries:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'active' AND query_start < now() - interval '5 minutes';"
   

3. Vacuum database:

   docker compose exec postgres psql -U postgres -d medusa -c "VACUUM ANALYZE;"
   

4. Rebuild indexes:

   docker compose exec postgres psql -U postgres -d medusa -c "REINDEX DATABASE medusa;"
   

5. Check table sizes:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) FROM pg_tables WHERE schemaname = 'public' ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;"
   

Redis Issues

Cannot Connect to Redis

Symptoms: - Connection refused - Timeout errors - Event bus not working

Solutions:

1. Check Redis is running:

   docker compose ps redis
   

2. Check REDIS_URL in .env:

   grep REDIS_URL .env
   

3. Test connection:

   docker compose exec redis redis-cli ping
   

4. Check Redis logs:

   docker compose logs redis
   

Redis Memory Issues

Symptoms: - Out of memory errors - Keys being evicted - Slow performance

Solutions:

1. Check memory usage:

   docker compose exec redis redis-cli INFO memory
   

2. Check key count:

   docker compose exec redis redis-cli DBSIZE
   

3. Clear cache (if safe):

   docker compose exec redis redis-cli FLUSHALL
   

4. Adjust maxmemory in docker-compose.yml:

   redis:
     command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
   

Backend Issues

Backend Won't Start

Symptoms: - Container exits immediately - Port 9000 not accessible - Build errors

Solutions:

1. Check backend logs:

   docker compose logs medusa
   

2. Check environment variables:

   docker compose exec medusa env
   

3. Verify dependencies installed:

   docker compose exec medusa npm ls
   

4. Rebuild backend:

   docker compose build medusa
   docker compose up -d medusa
   

Module Not Loading

Symptoms: - Module service not found - Route returns 404 - Module not registered

Solutions:

1. Check module registration in medusa-config.ts:

   docker compose exec medusa cat medusa-config.ts | grep -A 5 modules
   

2. Check module files exist:

   docker compose exec medusa ls -la src/modules/
   

3. Check for TypeScript errors:

   docker compose exec medusa npm run build
   

4. Restart backend:

   docker compose restart medusa
   

Workflow Fails

Symptoms: - Order creation fails - Workflow steps error - Compensation not running

Solutions:

1. Check workflow logs:

   docker compose logs medusa | grep -i workflow
   

2. Check workflow definition:

   docker compose exec medusa cat src/workflows/create-order-atomic.ts
   

3. Verify all steps are defined:

   docker compose exec medusa cat src/workflows/create-order-atomic.ts | grep "defineStep"
   

4. Check for missing dependencies:

   docker compose exec medusa npm ls | grep @medusajs
   

Frontend Issues

Frontend Won't Load

Symptoms: - Blank page - 404 errors - Build failures

Solutions:

1. Check store logs:

   docker compose logs store
   

2. Check Nginx configuration:

   docker compose exec store cat /etc/nginx/conf.d/default.conf
   

3. Check API base URL:

   grep VITE_API_BASE_URL frontend/store/.env
   

4. Rebuild frontend:

   docker compose build store
   docker compose up -d store
   

API Calls Failing

Symptoms: - CORS errors - Network errors - 401/403 errors

Solutions:

1. Check CORS configuration:

   grep CORS .env
   

2. Check backend is accessible:

   curl http://localhost:9000/store/translations
   

3. Check browser console for errors

4. Verify API base URL in frontend/store/src/services/api.js
5. Check authentication token:

   # In browser console
   localStorage.getItem('token')
   

API Issues

404 Not Found

Symptoms: - API endpoint returns 404 - Route not registered

Solutions:

1. Verify route file exists:

   docker compose exec medusa ls -la src/api/store/custom/
   

2. Check route is exported:

   docker compose exec medusa cat src/api/store/custom/translations/route.ts
   

3. Restart backend:

   docker compose restart medusa
   

4. Check URL path:

   curl -v http://localhost:9000/store/translations
   

500 Internal Server Error

Symptoms: - API returns 500 - Unhandled exceptions

Solutions:

1. Check backend logs:

   docker compose logs -f medusa
   

2. Check for TypeScript errors:

   docker compose exec medusa npm run build
   

3. Verify service methods exist:

   docker compose exec medusa cat src/modules/translation/service.ts
   

4. Check database connection:

   docker compose exec postgres pg_isready -U postgres
   

Authentication Errors

Symptoms: - 401 Unauthorized - Token invalid - Session expired

Solutions:

1. Check JWT secret:

   grep JWT_SECRET .env
   

2. Verify token format:

   # In browser console
   const token = localStorage.getItem('token')
   console.log(token)
   

3. Check admin session:

   # In browser dev tools
   document.cookie
   

4. Clear local storage and cookies:

   localStorage.clear()
   document.cookie.split(";").forEach(c => document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/"))
   

Migration Issues

Migration Script Fails

Symptoms: - Script exits with error - Data not migrated - Connection errors

Solutions:

1. Check Supabase credentials:

   grep SUPABASE .env
   

2. Test Supabase connection:

   curl -I https://your-project.supabase.co
   

3. Check script logs:

   docker compose exec medusa npx ts-node scripts/migrate-from-supabase.ts
   

4. Verify Supabase tables exist:

   # Use Supabase dashboard or SQL client
   

Verification Fails

Symptoms: - Count mismatch - Data integrity errors - Sample check failures

Solutions:

1. Re-run migration:

   docker compose exec medusa npx ts-node scripts/migrate-from-supabase.ts
   

2. Check for duplicates:

   docker compose exec postgres psql -U postgres -d medusa -c "SELECT id, COUNT(*) FROM advertisement GROUP BY id HAVING COUNT(*) > 1;"
   

3. Remove duplicates:

   docker compose exec postgres psql -U postgres -d medusa -c "DELETE FROM advertisement a1 USING advertisement a2 WHERE a1.id = a2.id AND a1.ctid < a2.ctid;"
   

4. Re-run verification:

   docker compose exec medusa npx ts-node scripts/verify-migration.ts
   

Performance Issues

Slow API Responses

Symptoms: - API calls take > 1 second - Frontend loading slowly - Database queries slow

Solutions:

1. Check backend response time:

   time curl http://localhost:9000/store/translations
   

2. Check database query performance:

   docker compose exec postgres psql -U postgres -d medusa -c "EXPLAIN ANALYZE SELECT * FROM translation;"
   

3. Add database indexes:

   CREATE INDEX idx_translation_language ON translation(language_code);
   CREATE INDEX idx_translation_key ON translation(key);
   

4. Enable Redis caching:

   docker compose exec redis redis-cli CONFIG SET save ""
   

High Memory Usage

Symptoms: - Container OOM killed - System slow - Memory leaks

Solutions:

1. Check container memory:

   docker stats
   

2. Check Node.js memory:

   docker compose exec medusa node -e "console.log(process.memoryUsage())"
   

3. Increase memory limit in docker-compose.yml:

   medusa:
     deploy:
       resources:
         limits:
           memory: 2G
   

4. Check for memory leaks:

   docker compose exec medusa npm run build -- --profile
   

Security Issues

Environment Variables Exposed

Symptoms: - Secrets in logs - .env committed to git - Secrets in error messages

Solutions:

1. Check .env is in .gitignore:

   grep .env .gitignore
   

2. Remove from git history:

   git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch .env' --prune-empty --tag-name-filter cat -- --all
   

3. Regenerate exposed secrets:

   openssl rand -base64 32
   

4. Update .env with new secrets

CORS Errors

Symptoms: - Browser CORS errors - API blocked - Mixed content errors

Solutions:

1. Check CORS configuration:

   grep CORS .env
   

2. Add frontend URL to CORS:

   STORE_CORS=http://localhost:3000,https://yourdomain.com
   ADMIN_CORS=http://localhost:9000,https://admin.yourdomain.com
   

3. Restart backend:

   docker compose restart medusa
   

4. Use HTTPS in production to avoid mixed content

Getting Help

Collect Diagnostic Information

1. System info:

   docker --version
   docker compose version
   node --version
   

2. Service status:

   docker compose ps
   

3. Recent logs:

   docker compose logs --tail=100
   

4. Environment variables:

   docker compose config
   

5. Database status:

   docker compose exec postgres pg_isready -U postgres
   

Where to Look for Help

1. Documentation: Check docs/ directory
2. MedusaJS Documentation: https://docs.medusajs.com
3. GitHub Issues: Search existing issues or create new one
4. Community Forums: MedusaJS Discord or community channels

Creating a Bug Report

Include:

1. Description: What happened
2. Steps to reproduce: How to trigger the issue
3. Expected behavior: What should happen
4. Actual behavior: What actually happened
5. Environment: OS, Docker version, Node version
6. Logs: Relevant error logs
7. Logs: Diagnostic information from above

Common Error Messages

"Cannot find module '@medusajs/framework'"

Cause: Dependencies not installed

Solution:

cd backend
npm install

"Connection refused"

Cause: Service not running or wrong port

Solution: Check service is running and port is correct

"Migration already applied"

Cause: Migration already run

Solution: This is normal, no action needed

"Out of memory"

Cause: Container memory limit exceeded

Solution: Increase memory limit or optimize code

"ECONNREFUSED"

Cause: Network connection issue

Solution: Check network connectivity and service status