Troubleshooting

Container Issues

Container won’t start

# Check logs
docker logs magic_{tenant}_backend_dev --tail=100

# Check if port is in use
lsof -i :4040

# Force recreate
cd /mnt/data/magic_omniverse/magic_commerce/magic_{tenant}
docker compose down
docker compose up -d

Build fails

# Clean build (no cache)
docker compose build backend --no-cache

# Check disk space
df -h /mnt/data
docker system prune  # Clean unused images/containers

Redis connection errors

# Check Redis health
docker exec magic_{tenant}_redis_dev redis-cli ping

# Restart Redis
docker compose restart redis

Database Issues

Can’t connect to PostgreSQL

# Check PostgreSQL is running
docker exec magic_pim_postgres_dev pg_isready -U postgres

# Test connection
docker exec magic_pim_postgres_dev psql -U postgres -l

# Check from a tenant container
docker exec magic_brinxx_backend_dev ping host.docker.internal

Database migration fails

# Run migration manually
docker exec magic_{tenant}_backend_dev npx medusa db:migrate

# Check migration status
docker exec magic_pim_postgres_dev psql -U postgres -d magic_b2b_{tenant} \
  -c "SELECT * FROM mikro_orm_migrations ORDER BY executed_at DESC LIMIT 5;"

Storefront Issues

404 on storefront

• Check Nginx config: nginx -t && systemctl reload nginx
• Verify container is running: docker ps | grep storefront
• Check storefront logs: docker logs magic_{tenant}_storefront_dev --tail=50

Images not loading

• Check PIM data mount: docker exec magic_{tenant}_backend_dev ls /mnt/data/pim_data/
• Verify Nginx serves /pim_data/ location
• Check image path format (lowercase .jpg, correct supplier prefix)

CORS errors

• Check STORE_CORS and ADMIN_CORS environment variables
• Ensure the domain is whitelisted in the tenant’s docker-compose.yml
• Restart backend after CORS changes

Nginx Issues

SSL certificate expired

# Renew certificates
certbot renew

# Test config
nginx -t

# Reload
systemctl reload nginx

Site not accessible

# Check Nginx status
systemctl status nginx

# Test config syntax
nginx -t

# Check specific site config
ls -la /etc/nginx/sites-enabled/ | grep {domain}

Common Errors

”APLT database connection failed”

• Check APLT_DB_HOST, APLT_DB_PORT, APLT_DB_NAME in docker-compose
• Verify PostgreSQL container is healthy
• Ensure host.docker.internal resolves (check extra_hosts in docker-compose)

“PDF generation error”

• Check PDFKit is installed: verify pdfkit in package.json
• Ensure /mnt/data/brinxx_invoices/ is writable
• Check aplt_cms_settings for company info

”Connector sync failed”

• Check supplier feed URL is accessible
• Verify connector is active in admin panel
• Check disk space for downloaded feed files

Useful Diagnostic Commands

# Check all containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | grep magic_

# Disk usage
df -h /mnt/data
du -sh /mnt/data/magic_omniverse/magic_commerce/*/

# Find large files
find /mnt/data -size +100M -type f

# Database sizes
docker exec magic_pim_postgres_dev psql -U postgres -c \
  "SELECT datname, pg_size_pretty(pg_database_size(datname)) FROM pg_database ORDER BY pg_database_size(datname) DESC;"

# Network connectivity
docker network ls | grep magic