Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Mercaline2024/Ecomdrop-ia-connector-2/llms.txt

Use this file to discover all available pages before exploring further.

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

Error: connect ECONNREFUSED mysql:3306
or
Can't connect to MySQL server on 'mysql' (111)
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

The table `Session` does not exist in the current database.
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

Client does not support authentication protocol requested by server
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

Error starting userland proxy: listen tcp 0.0.0.0:3000: bind: address already in use
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

Port 3306 already in use by another MySQL instance.
# Stop local MySQL service
sudo systemctl stop mysql
sudo systemctl disable mysql

Build Errors

npm ci Failed

npm ERR! The `npm ci` command can only install packages when your package.json and package-lock.json are in sync
# 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

Error: @prisma/client did not initialize yet
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

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
# 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

Service keeps restarting or shows “Shutdown” status.
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

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
MySQL did not become available after 60 seconds
Solution: Increase wait timeout in Dockerfile or ensure MySQL has enough resources.
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

After running docker service update, service fails to start.
# 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

Browser shows “Not Secure” or certificate errors.
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

Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure resource
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

Accessing https://connector.ecomdrop.io returns 404.
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)

504 Gateway Timeout
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

Application uses excessive memory or gets OOM killed.
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

Application responses are slow.
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

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

Cause: Prisma Client not generated.Solution:
docker exec -it $(docker ps -q -f name=shopify-app_shopify_app) \
  npx prisma generate
Cause: Missing environment variable.Solution: Add to .env and redeploy:
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_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
Cause: External network doesn’t exist.Solution:
docker network create --driver overlay EcomdropNet
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
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

Build docs developers (and LLMs) love