Troubleshooting

Common issues and their solutions for MediaMagic CRM.

Quick Diagnostics

Run these commands to check system health:

Service Status

docker compose ps

View Logs

docker compose logs -f --tail=100

Bridge Health

curl http://localhost:3100/health

Service Issues

EspoCRM Not Starting

Symptom: EspoCRM container keeps restarting

Check MySQL health:

docker compose logs espocrm-mysql

Common causes:

1. MySQL not ready before EspoCRM starts
2. Insufficient permissions on volumes
3. Corrupted database

Solution:

# Restart in correct order
docker compose stop espocrm
docker compose up -d espocrm-mysql
sleep 30  # Wait for MySQL
docker compose up -d espocrm

Symptom: "Database connection failed"

Check credentials match:

• .env file: MYSQL_PASSWORD
• Match between EspoCRM and MySQL containers

Solution:

# Reset with fresh database
docker compose down
docker volume rm crm_mysql-data
docker compose up -d

Bridge API Issues

Symptom: Bridge container exits immediately

Check logs:

docker compose logs bridge

Common causes:

1. Missing environment variables
2. Syntax error in code
3. Dependency issues

Solution:

# Rebuild bridge
docker compose build bridge
docker compose up -d bridge

Symptom: Bridge returns 500 errors

Check logs for error details:

docker compose logs bridge --tail=50

Common causes:

1. EspoCRM API key invalid
2. External service down
3. Database connection issue

Verify connections:

# From bridge container
docker compose exec bridge sh
curl http://espocrm/api/v1/App/user

PostgreSQL Issues

Symptom: Grafana shows "No data"

Check PostgreSQL connection:

docker compose exec postgres psql -U mediamagic -d mediamagic_analytics -c "SELECT 1"

Check tables exist:

docker compose exec postgres psql -U mediamagic -d mediamagic_analytics -c "\dt"

Re-seed if needed:

docker compose exec -T postgres psql -U mediamagic -d mediamagic_analytics < postgres/seed-data.sql

Webhook Issues

Webhooks Not Firing

Verify webhook configuration in EspoCRM

1. Go to Admin → Webhooks
2. Check each webhook has:
   • URL: http://bridge:3100/webhooks/{event-name}
   • Entity Type: Correct entity
   • Event: Create, Update, or Delete
   • Is Active: Yes

Test webhook manually

# Send test webhook
curl -X POST http://localhost:3100/webhooks/test \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Publishing Issues

Platform Publish Stuck in "Queued"

Check X Server connectivity

# From bridge container
docker compose exec bridge sh
curl $X_SERVER_URL/health

If not reachable:

• Verify X_SERVER_URL in .env
• Check X Server is running
• Check firewall rules

Check platform routes

Verify platform is in PLATFORM_ROUTES:

// bridge/routes/webhooks.js
const PLATFORM_ROUTES = {
  'YourPlatform': { 
    livestream: '/yourplatform-create', 
    upload: '/yourplatform-upload' 
  },
};

Platform Publish Failed

Check error details

1. In EspoCRM, open the failed PlatformPublish record
2. Check the apiResponse field for error details
3. Common errors:
   • Authentication failed: Platform credentials expired
   • Rate limited: Too many requests
   • Invalid data: Missing required fields

Retry a failed publish

Simply set status back to "Queued":

# Via EspoCRM UI
# Or via API:
curl -X PUT http://localhost:8080/api/v1/PlatformPublish/{id} \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"status": "Queued"}'

Social Post Issues

Posts Not Scheduling

Check Ayrshare connection

# Test Ayrshare API
curl -X GET https://app.ayrshare.com/api/user \
  -H "Authorization: Bearer YOUR_AYRSHARE_KEY"

If 401 error: API key is invalid or expired.

Check scheduling payload

View what's being sent to Ayrshare:

docker compose logs bridge | grep -i ayrshare

Ensure scheduledAt is in the future.

Analytics Not Collecting

Manually trigger collection

curl -X POST http://localhost:3100/analytics/collect

Check response for errors.

Check cron job

The analytics cron runs every 6 hours. Check if it's running:

docker compose logs bridge | grep -i "analytics\|cron"

Database Issues

Reset All Data

Warning

This deletes ALL data. Make a backup first!

# Backup first
./backup.sh

# Stop everything
docker compose down

# Remove volumes
docker volume rm crm_mysql-data crm_espocrm-data crm_grafana-data crm_postgres-data

# Start fresh
docker compose up -d

Restore from Backup

# Stop services
docker compose down

# Restore volumes from backup
# (depends on backup format)

# Start services
docker compose up -d

Viewing Logs

All Services

docker compose logs -f

Specific Service

docker compose logs -f bridge
docker compose logs -f espocrm
docker compose logs -f postgres
docker compose logs -f grafana

Filter by Time

# Last hour
docker compose logs --since 1h bridge

# Last 100 lines
docker compose logs --tail 100 bridge

Getting Help

1. Check logs — Most issues are visible in container logs
2. Check .env — Many issues are configuration-related
3. Restart services — Sometimes a restart fixes transient issues
4. Check GitHub issues — Someone may have had the same problem

# Quick health check script
echo "=== Service Status ==="
docker compose ps

echo "=== Bridge Health ==="
curl -s http://localhost:3100/health | jq

echo "=== Recent Errors ==="
docker compose logs --tail 20 2>&1 | grep -i "error\|fail\|exception"