Troubleshooting

Common issues and solutions for deploying the Ecomdrop IA Connector

Overview

This guide covers common issues you may encounter when deploying the Ecomdrop IA Connector and provides step-by-step solutions.

Database Connection Issues

MySQL Connection Refused

Symptom

Error: connect ECONNREFUSED mysql:3306

or

Can't connect to MySQL server on 'mysql' (111)

Solution

1. Verify MySQL is running

   # Check MySQL service status
   docker service ps shopify-app_mysql
   
   # Check MySQL logs
   docker service logs shopify-app_mysql
   
2. Wait for MySQL to be ready

   The application includes a wait script, but if it times out:

   # Check if MySQL is accepting connections
   docker exec $(docker ps -q -f name=shopify-app_mysql) \
     mysqladmin ping -h localhost -uroot -p${MYSQL_ROOT_PASSWORD}
   

   Expected output: mysqld is alive

3. Verify network connectivity

   # Check if both services are on the same network
   docker network inspect EcomdropNet
   

   Both mysql and shopify_app should be listed.

4. Check DATABASE_URL format

   Ensure your .env has the correct format:

   DATABASE_URL="mysql://shopify_user:${MYSQL_PASSWORD}@mysql:3306/shopify_app"
   

   The hostname must be mysql (the service name), not localhost or an IP address.

Database Tables Don’t Exist

Symptom

The table `Session` does not exist in the current database.

Solution

1. Check if migrations ran

   # View application logs
   docker service logs shopify-app_shopify_app | grep "prisma migrate"
   
2. Run migrations manually

   # Execute in a running container
   docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
     npm run setup
   
3. Verify database schema

   # Connect to MySQL
   docker exec -it $(docker ps -q -f name=shopify-app_mysql) \
     mysql -u shopify_user -p${MYSQL_PASSWORD} shopify_app
   
   # In MySQL shell
   SHOW TABLES;
   

   You should see: Session, ShopConfiguration, ProductAssociation, AIConfiguration, etc.

4. If tables still missing, reset database

   This will delete all data!

   # Drop and recreate database
   docker exec -it $(docker ps -q -f name=shopify-app_mysql) \
     mysql -u root -p${MYSQL_ROOT_PASSWORD} -e "
       DROP DATABASE IF EXISTS shopify_app;
       CREATE DATABASE shopify_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
       GRANT ALL PRIVILEGES ON shopify_app.* TO 'shopify_user'@'%';
       FLUSH PRIVILEGES;
     "
   
   # Restart application to run migrations
   docker service update --force shopify-app_shopify_app
   

Authentication Plugin Error

Symptom

Client does not support authentication protocol requested by server

Solution

The MySQL service is configured with mysql_native_password, but if you still see this error:

# Connect to MySQL
docker exec -it $(docker ps -q -f name=shopify-app_mysql) \
  mysql -u root -p${MYSQL_ROOT_PASSWORD}

# In MySQL shell
ALTER USER 'shopify_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;

Port Conflicts

Port Already in Use

Symptom

Error starting userland proxy: listen tcp 0.0.0.0:3000: bind: address already in use

Solution

1. Find process using the port

   # Find process on port 3000
   lsof -i :3000
   # or
   netstat -tlnp | grep :3000
   
2. Stop the conflicting process

   # Kill the process (replace PID with actual process ID)
   kill -9 <PID>
   
3. Or change the application port

   In .env:

   PORT=3001
   

   If using Traefik, the internal port doesn’t matter as Traefik handles external routing.

MySQL Port Conflict

Symptom

Port 3306 already in use by another MySQL instance.

Solution

Stop Local MySQL

# Stop local MySQL service
sudo systemctl stop mysql
sudo systemctl disable mysql

Build Errors

npm ci Failed

Symptom

npm ERR! The `npm ci` command can only install packages when your package.json and package-lock.json are in sync

Solution

# Update package-lock.json
npm install

# Commit updated package-lock.json
git add package-lock.json
git commit -m "Update package-lock.json"

# Rebuild Docker image
docker build -t shopify-app_shopify_app:latest .

Build Fails on Prisma Generate

Symptom

Error: @prisma/client did not initialize yet

Solution

1. Verify Prisma schema is valid

   npx prisma validate
   
2. Ensure database URL is set during build

   The Dockerfile needs a placeholder DATABASE_URL during build:

   # In Dockerfile, add before npm run build
   ENV DATABASE_URL="mysql://user:pass@localhost:3306/db"
   
3. Rebuild with build args

   docker build \
     --build-arg DATABASE_URL="mysql://user:pass@localhost:3306/db" \
     -t shopify-app_shopify_app:latest .
   

Out of Memory During Build

Symptom

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Solution

# Build with increased memory
docker build \
  --memory=4g \
  -t shopify-app_shopify_app:latest .

# Or add to Dockerfile
ENV NODE_OPTIONS="--max-old-space-size=4096"

Application Startup Issues

Application Crashes on Startup

Symptom

Service keeps restarting or shows “Shutdown” status.

Solution

1. Check application logs

   # View recent logs
   docker service logs --tail 100 shopify-app_shopify_app
   
   # Follow logs in real-time
   docker service logs -f shopify-app_shopify_app
   
2. Common startup errors

   Missing environment variables

   Error: SHOPIFY_API_KEY is required
   

   Solution: Verify all required environment variables in .env:

   docker service inspect shopify-app_shopify_app --pretty | grep -A 20 Env
   

   Database migration timeout

   MySQL did not become available after 60 seconds
   

   Solution: Increase wait timeout in Dockerfile or ensure MySQL has enough resources.

   Port binding issues

   Error: listen EADDRINUSE: address already in use :::3000
   

   Solution: See Port Conflicts section.

3. Verify service configuration

   # Inspect service
   docker service inspect shopify-app_shopify_app --pretty
   
   # Check task status
   docker service ps shopify-app_shopify_app --no-trunc
   

Service Won’t Start After Update

Symptom

After running docker service update, service fails to start.

Solution

# Rollback to previous version
docker service rollback shopify-app_shopify_app

# Check what went wrong
docker service ps shopify-app_shopify_app

# Force recreation
docker service update --force shopify-app_shopify_app

SSL/HTTPS Issues

Let’s Encrypt Certificate Not Issued

Symptom

Browser shows “Not Secure” or certificate errors.

Solution

1. Check Traefik logs

   docker service logs traefik | grep -i acme
   docker service logs traefik | grep -i letsencrypt
   
2. Verify DNS is correct

   # Check DNS resolution
   nslookup connector.ecomdrop.io
   dig connector.ecomdrop.io
   
   # Should point to your server IP
   
3. Ensure port 80 is accessible

   Let’s Encrypt uses HTTP-01 challenge on port 80:

   # Test from external server or use online tools
   curl -I http://connector.ecomdrop.io
   
4. Check rate limits

   Let’s Encrypt has rate limits (50 certificates per domain per week).

   If you hit the limit, use Let’s Encrypt staging:

   # In traefik.yml
   certificatesResolvers:
     letsencryptresolver:
       acme:
         caServer: https://acme-staging-v02.api.letsencrypt.org/directory
   
5. Reset ACME storage

   This will delete existing certificates!

   # Remove ACME storage
   docker volume rm traefik_traefik-certificates
   
   # Restart Traefik
   docker service update --force traefik_traefik
   

Mixed Content Warnings

Symptom

Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure resource

Solution

Ensure all resources use HTTPS or protocol-relative URLs:

// Bad
<script src="http://example.com/script.js"></script>

// Good
<script src="https://example.com/script.js"></script>

// Also good (protocol-relative)
<script src="//example.com/script.js"></script>

Traefik Routing Issues

404 Not Found

Symptom

Accessing https://connector.ecomdrop.io returns 404.

Solution

1. Verify service labels

   docker service inspect shopify-app_shopify_app --pretty | grep -A 10 Labels
   

   Should include:

   traefik.enable=true
   traefik.http.routers.shopify_app.rule=Host(`connector.ecomdrop.io`)
   
2. Check Traefik can reach the service

   # Verify both on same network
   docker network inspect EcomdropNet
   
3. Test internal connectivity

   # From within Traefik container
   docker exec -it $(docker ps -q -f name=traefik) \
     wget -O- http://shopify_app:3000
   
4. Check Traefik dashboard

   If Traefik dashboard is enabled, check for the router and service at https://traefik.ecomdrop.io

Gateway Timeout (504)

Symptom

504 Gateway Timeout

Solution

1. Check application is responding

   # Test directly
   docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
     wget -O- http://localhost:3000
   
2. Increase timeout in Traefik

   Add to docker-compose.yml labels:

   - traefik.http.services.shopify_app.loadbalancer.server.responseTimeout=60s
   
3. Check for slow database queries

   # Enable MySQL slow query log
   docker exec -it $(docker ps -q -f name=shopify-app_mysql) \
     mysql -u root -p${MYSQL_ROOT_PASSWORD} -e "
       SET GLOBAL slow_query_log = 'ON';
       SET GLOBAL long_query_time = 2;
     "
   

Performance Issues

High Memory Usage

Symptom

Application uses excessive memory or gets OOM killed.

Solution

1. Monitor resource usage

   # Real-time monitoring
   docker stats
   
   # Check service resources
   docker service ps shopify-app_shopify_app --no-trunc
   
2. Set memory limits

   In docker-compose.yml:

   deploy:
     resources:
       limits:
         memory: 1G
       reservations:
         memory: 512M
   
3. Optimize Node.js memory

   environment:
     NODE_OPTIONS: "--max-old-space-size=768"
   

Slow Database Queries

Symptom

Application responses are slow.

Solution

1. Enable slow query log

   docker exec -it $(docker ps -q -f name=shopify-app_mysql) \
     mysql -u root -p${MYSQL_ROOT_PASSWORD} -e "
       SET GLOBAL slow_query_log = 'ON';
       SET GLOBAL long_query_time = 1;
       SET GLOBAL log_queries_not_using_indexes = 'ON';
     "
   
2. Check for missing indexes

   -- In MySQL
   SELECT * FROM information_schema.STATISTICS 
   WHERE TABLE_SCHEMA = 'shopify_app';
   
3. Optimize MySQL configuration

   See Production Deployment - MySQL Tuning

Debugging Tools

Interactive Shell in Container

# Application container
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) sh

# MySQL container
docker exec -it $(docker ps -q -f name=shopify-app_mysql) bash

Network Debugging

# Install network tools in container
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  apk add --no-cache curl netcat-openbsd

# Test connectivity
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  nc -zv mysql 3306

View Container Processes

# Show processes in container
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) ps aux

Export Container Logs

# Export last 24 hours of logs
docker service logs --since 24h shopify-app_shopify_app > app-debug-$(date +%Y%m%d).log

# Export with timestamps
docker service logs --timestamps shopify-app_shopify_app > app-debug-timestamps.log

Common Error Messages

Error: Cannot find module '@prisma/client'

Cause: Prisma Client not generated.

Solution:

docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  npx prisma generate

Error: SHOPIFY_API_KEY is required

Cause: Missing environment variable.

Solution: Add to .env and redeploy:

SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

Error: Invalid SESSION_SECRET

Cause: Session secret not set or invalid.

Solution:

# Generate new session secret
openssl rand -base64 32

# Add to .env
SESSION_SECRET=generated_secret_here

Network shopify-app_EcomdropNet not found

Cause: External network doesn’t exist.

Solution:

docker network create --driver overlay EcomdropNet

Failed to load: api.shopify.com

Cause: Network connectivity issues or firewall blocking.

Solution:

# Test connectivity
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  wget -O- https://api.shopify.com

# Check DNS
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  nslookup api.shopify.com

Getting Help

If you’re still experiencing issues:

1. Gather diagnostic information

   # Create diagnostic report
   {
     echo "=== Docker Version ==="
     docker version
     echo ""
     echo "=== Service Status ==="
     docker service ls
     echo ""
     echo "=== Application Service ==="
     docker service ps shopify-app_shopify_app --no-trunc
     echo ""
     echo "=== Application Logs ==="
     docker service logs --tail 50 shopify-app_shopify_app
     echo ""
     echo "=== MySQL Service ==="
     docker service ps shopify-app_mysql --no-trunc
     echo ""
     echo "=== MySQL Logs ==="
     docker service logs --tail 50 shopify-app_mysql
   } > diagnostic-report-$(date +%Y%m%d_%H%M%S).txt
   
2. Check documentation

   • Docker Deployment Guide
   • Production Deployment Guide
   • Shopify App Documentation
3. Review logs carefully

   Error messages usually contain valuable information about the root cause.

4. Search for similar issues

   Check GitHub issues for the project repository.

Preventive Measures

Regular Backups

Set up automated database backups to prevent data loss.

See Production Deployment - Database Backups

Monitoring

Monitor your application health:

• Resource usage (CPU, memory, disk)
• Error rates
• Response times

Health Checks

Configure proper health checks:

healthcheck:
  test: ["CMD", "wget", "-O-", "http://localhost:3000/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Log Retention

Configure log rotation to prevent disk space issues:

docker service update \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  shopify-app_shopify_app